Windows Installer

Version 1.5

Purpose

The Microsoft® Windows® Installer is an installation and configuration service that ships as part of the Microsoft Windows 2000 and Windows® Millennium Edition (Windows Me) operating systems, and is provided in a service pack to Windows 95, Windows 98, and Microsoft Windows NT® version 4.0. Customers wanted an installer that better addressed the needs of corporate deployment and provided a standard format for component management.

Where Applicable

Windows Installer reduces the total cost of ownership (TCO) for your customers by enabling them to efficiently install and configure your products and applications. The installer can also provide your product with new capabilities to advertise features without installing them, to install products on demand, and to add user customizations.

Developer Audience

This documentation is intended for software developers who want to make applications that use Windows Installer. As the primary source of reference material for the installer, it provides general background information about installation packages and the installer service. It contains complete descriptions of the application programming interface (API) and the elements of the installer database. This documentation also contains supplemental information of interest to developers who want to use a table editor or a package creation tool to make or maintain an installation.

Run-time Requirements

Requires Windows NT 4.0 with Service Pack 3 or later, Windows 2000, or Windows Me. Available as a redistributable for Windows NT 4.0. Requires Windows 95 or later. Available as a redistributable for Windows 95 and Windows 98. The Windows Installer supports advertisement of applications and features according to the operating system. For more information, see Platform Support of Advertisement.

Roadmap

A guide to Windows Installer documentation.

Overview

General information about the installer.

Reference

Documentation of Windows Installer functions.

Feedback

Make error reports and feature requests directly to Microsoft.

Built on Tuesday, October 24, 2000


Legal Information

Windows Installer

(Build 216) (This build began on October 23, 2000)

This is a preliminary document and may be changed substantially prior to final commercial release. This document is provided for informational purposes only and Microsoft makes no warranties, either express or implied, in this document. Information in this document, including URL and other Internet Web site references, is subject to change without notice. The entire risk of the use or the results of the use of this document remains with the user. Unless otherwise noted, the example companies, organizations, products, people and events depicted herein are fictitious and no association with any real company, organization, product, person or event is intended or should be inferred. Complying with all applicable copyright laws is the responsibility of the user. Without limiting the rights under copyright, no part of this document may be reproduced, stored in or introduced into a retrieval system, or transmitted in any form or by any means (electronic, mechanical, photocopying, recording, or otherwise), or for any purpose, without the express written permission of Microsoft Corporation.

Microsoft may have patents, patent applications, trademarks, copyrights, or other intellectual property rights covering subject matter in this document. Except as expressly provided in any written license agreement from Microsoft, the furnishing of this document does not give you any license to these patents, trademarks, copyrights, or other intellectual property.

© 2000 Microsoft Corporation. All rights reserved.

ActiveX, BackOffice, DirectX, JScript, Microsoft, Microsoft Press, MS-DOS, MSDN, Visual Basic, Visual C++, Windows, Win32, Win32s, and Windows NT are either registered trademarks or trademarks of Microsoft Corporation in the U.S.A. and/or other countries.

The names of actual companies and products mentioned herein may be the trademarks of their respective owners.


Roadmap to Windows Installer Documentation

This documentation is intended for software developers who want to make applications that use the Microsoft® Windows® installer. As the primary source of reference material for the installer, it provides general background information about installation packages and the installer service. It contains complete descriptions of the application programming interface (API) and the elements of the installer database. This documentation also contains supplemental information of interest to developers who want to use a table editor or a package creation tool to make or maintain an installation. These supplemental sections discuss an example installation package and user interface, merge modules, updating, and validation.

The following list describes each section of the installer documentation. Most of these sections are divided into About, Using, and Reference subsections.

  • About Windows Installer gives an overview of installer capabilities and benefits, such as advertisement, installation-on-demand, resiliency, customization, and component management. This section introduces the concepts of installer components and features, which are essential to understanding how the installer organizes an installation. It also discusses several high-level subjects about installations, such as System Policy, File Versioning Rules, and Rollback Installation.
  • Using Windows Installer currently discusses three subjects on using the installer. Organizing Applications into Components discusses a standard method for organizing an application into components that the installer can install or remove from a user's machine. Downloading an Installation From the Internet describes how to download an installation package located at a URL. Using Cabinets and Compressed Sources discusses using compressed source images.
  • Windows Installer on 64-bit Operating Systems describes how to use Windows Installer version 1.5 to install and manage installer components designed to run on 64-bit operating systems.
  • Assemblies describes how to use Windows Installer version 1.5 to install and manage common language runtime and Win32® assemblies.
  • Installer Functions describes function calls to the installer service API. These are the functions that other applications call to access the installer services to install, maintain, or remove applications. The Using sections includes discussions of how to request features, initiate installations, and reinstall missing components programmatically. The Reference section is the primary reference material for the installer service functions.
  • Installer Database describes the installation database. The installer keeps all of the logic and data necessary for an installation in a relational database located in an .msi file. The About section provides an overview with schema diagrams for the major functional groups of tables of the database. The Using section discusses working with the most important of these tables. These sections contain information that is essential to developers who are authoring installation packages or writing package creation tools. The Reference section contains complete reference material for each database table. This section also contains the primary reference for each of the database functions. The database functions are used internally by the installer to access the database and are primarily of interest to developers of installer package creation tools.
  • User Interface gives information about the installer's user interface capabilities. Although the installer does not provide a user interface, a package author can keep all the data and logic required to run a fully interactive internal or external user interface in the installation database. The Reference section describes elements of the user interface that are specifiable in the database tables, including dialog boxes, controls, and control events.
  • Standard Actions gives information about the standard actions used by the installer in the sequence tables to perform an installation. This information is intended primarily for package developers.
  • Custom Actions gives information about creating additional functionality in the installer. Custom actions enable the author of an installation package to extend the capabilities of standard actions by including executables, dynamic-link libraries, and script. This information is intended for package developers who need to perform installation functions not found elsewhere in the installer.
  • Properties gives information about the properties the installer uses during an installation. The About and Using sections gives an overview of these global variables and each property is described in the Reference section.
  • Summary Information Stream documents the summary information properties used by the installer. This information is of interest to all developers.
  • Automation Interface provides information to developers who want to use the automation interface of the Windows Installer.
  • Patching and Upgrades discusses using the installer to perform File Updates, QFEs, Minor Updates, Product Upgrades, and Patching.
  • Transforms discusses how to alter or customize an installation database using a database transform and how to generate, secure, and apply transforms.
  • Package Validation discusses using Internal Consistency Evaluators (ICEs) to test the internal consistency of installation packages that are under development.
  • Merge Modules presents a standard for the design of merge modules. This standard should be followed by developers who are creating their own merge modules as well as by developers who plan to use the installer to deliver shared code to their applications.
  • Windows Installer Examples includes a step-by-step example of creating an installation package with an internal user interface in An Installation Example. For an example of authoring a major upgrade for an existing package, see An Upgrade Example. To learn how a customization transform disables features and adds new resources, see A Customization Transform Example. For an example of creating a patch package that applies a small update to an existing installation package, see A Small Update Patching Example. To learn how to localize an existing installer package, see A Localization Example.
  • Glossary
  • Appendix contains a list of command line options and other miscellaneous information.


What's New in Windows Installer version 1.5

[This is preliminary documentation and subject to change.]

The following list outlines additions and changes to Microsoft® Windows® Installer available in Windows Installer version 1.5 or later.

New Installer Functions

MsiGetFileHash

MsiGetFileSignatureInformation

The Installer Functions of the Windows Installer version 1.5 supports both 32-bit and 64-bit applications and processes.

New Database Functions

The Database Functions of the Windows Installer supports both 32-bit and 64-bit applications and processes.

New Database Tables

MsiAssembly Table

MsiAssemblyName Table

MsiDigitalCertificate Table

MsiDigitalSignature Table

MsiFileHash Table

New Table Columns

None

New Standard Actions

MsiPublishAssemblies action

MsiUnPublishAssemblies action

New Custom Actions

None

New Properties

CommonFiles64Folder Property

Intel64 Property

MsiNTProductType Property

MsiNTSuiteBackOffice Property

MsiNTSuiteDataCenter Property

MsiNTSuiteEnterprise Property

MsiNTSuiteSmallBusiness Property

MsiNTSuiteSmallBusinessRestricted Property

MsiNTSuitePersonal Property

ProgramFiles64Folder Property

System64Folder Property

VersionNT64 Property

Removed Properties

System16Folder Property

Revised Properties

SHORTFILENAMES

SOURCELIST

New Attributes

msidbComponentAttributes64bit

msidbLocatorType64bit

New System Policies

None

New Error Codes

None

New Return Values

ERROR_INSTALL_PLATFORM_UNSUPPORTED.

New Internal Consistency Evaluators (ICEs)

ICE75

ICE77

ICE78

ICEM11

ICEM12

Note Beginning with Windows Installer version 1.5, you can install 64-bit Windows Installer packages. A 64-bit package is indicated by entering the value Intel64 in the Template Summary Property. The schema of a 64-bit package must be 150 or greater. Therefore the Page Count Summary Property of a 64-bit package must be 150 or greater. If a version of Windows Installer earlier than version 1.5 is called to install a 64-bit package, it returns the following error requesting that the user update the Windows Installer: ERROR_INSTALL_PLATFORM_UNSUPPORTED - "This installation package is not supported on this platform. Contact your application vendor."

Also beginning with Windows Installer version 1.5, the installer adds debugging information to the installation log file for custom action scripts.

With Windows Installer version 1.5, a component may be added to an existing feature by an update or patch without a required product code change. For more information, see Changing the Product Code.


What's New in Windows Installer version 1.2

The following list outlines additions and changes to Microsoft® Windows® Installer available in Windows Installer version 1.2 or later.

New Functions

None

New Database Tables

FileSFPCatalog table

SFPCatalog table

New Table Columns

None

New Standard Actions

InstallSFPCatalogFile action

New Custom Actions

None

New Properties

FASTOEM

MEDIAPACKAGEPATH

New Attributes

None

New System Policies

None

New Error Codes

None

New Return Values

None

Note Windows File Protection On Windows Millennium Edition is supported by Windows Installer version 1.2 but not supported by Windows Installer version 1.0 or 1.1.


What's New in Windows Installer version 1.1

The following list outlines additions and changes to Microsoft® Windows® Installer available in Windows Installer version 1.1 or later.

New Functions

MsiEnumRelatedProducts

MsiSetFeatureAttributes

MsiSourceListForceResolution

MsiSourceListAddSource

MsiSourceListClearAll

MsiGetShortcutTarget

New Database Tables

Complus table

Upgrade table

IsolatedComponent table

New Table Columns

Description in the ServiceInstall table

Attributes in the Class table

New Standard Actions

RegisterComPlus action

UnregisterComPlus action

FindRelatedProducts action

PreventInstall action

MigrateFeatureStates action

RemoveExistingProducts action

IsolateComponents action

New Custom Actions

Nested Installations

Custom Action Type 7

Custom Action Type 23

Custom Action Type 39

New Properties

AdminToolsFolder property

LocalAppDataFolder property

CommonAppDataFolder property

MyPicturesFolder property

RedirectedDLLSupport property

ServicePackLevelMinor property

TRANSFORMSSECURE property

RemoteAdminTS property

REBOOTPROMPT property

New Attributes

Password (Edit control attribute)

New System Policies

AllowLockdownBrowse

AllowLockdownMedia

AllowLockdownPatch

TransformsSecure

DisableRollback

EnableAdminTSRemote

New Error Codes

ERROR_SUCCESS_REBOOT_INITIATED

ERROR_SUCCESS_REBOOT_REQUIRED

ERROR_PATCH_TARGET_NOT_FOUND

ERROR_INSTALL_REMOTE_DISALLOWED

New Return Values

MsiSetComponentState now returns ERROR_INSTALL_USEREXIT.

Note The Alpha platform is not supported by Windows Installer version 1.1.


About Windows Installer

To install your applications efficiently and reduce the total cost of ownership (TCO) for your customers, you can use the Microsoft® Windows® Installer. This section covers the major functional areas of the installer:

  • Overview of Windows Installer
  • Administrative Installation
  • Rollback Installation
  • Maintenance Installation
  • System Reboots
  • System Policy
  • Source Resiliency
  • File Versioning Rules
  • Product Codes
  • Package Codes
  • Merges and Transforms
  • Qualified Components
  • Logging
  • Companion Files
  • Isolated Components


Overview of Windows Installer

The Microsoft® Windows® Installer reduces the total cost of ownership (TCO) for your customers by enabling them to efficiently install and configure your products and applications. The installer can also provide your product with new capabilities to advertise features without installing them, to install products on demand, and to add user customizations.

The following sections provide a high-level overview of the installer:

  • Installation Package
  • Components and Features
  • Installation Mechanism
  • Component Management
  • Advertisement
  • Installation-On-Demand
  • Resiliency
  • Customization


Installation Package

An installation package contains all the information the Microsoft® Windows® Installer requires to install or uninstall an application or product and to run the setup user interface. Each installation package includes an .msi file, containing an installation database, a summary information stream, and data streams for various parts of the installation. The .msi file can also contain one or more transforms, internal source files, and external source files or cabinet files required by the installation.

Application developers must author an installation to use the installer. Because the installer organizes installations around the concept of components and features, and stores all information about the installation in a relational database, the process of authoring an installation package broadly entails the following steps:

  • Identify the features to be presented to users.
  • Organize the application into components.
  • Populate the installation database with information.
  • Validate the installation package.

The next section discusses installer components and features. For more information, see Components and Features. The choice of features is commonly determined by the application's functionality from the user's perspective.

It is recommended that developers use a standard procedure for choosing components. For more information, see Organizing Applications into Components.

Package authors can use third-party package creation tools, or a table editor and the Windows Installer SDK, to populate the installation database. All installation packages need to be validated for internal consistency. For more information, see Package Validation.


Components and Features

The Microsoft® Windows® Installer organizes an installation around the concepts of components and features.

A feature is a part of the application's total functionality that a user may decide to install independently. For more information, see Windows Installer Features.

A component is a piece of the application or product to be installed. The installer always installs or removes a component from a user's computer as a coherent piece. Components are usually hidden from the user. When a user selects a feature for installation, the installer determines which components must be installed to provide that feature. For more information, see Windows Installer Components.

Authors of installation packages need to decide how to divide their application into features and components. The selection of features is primarily determined by the application's functionality from the user's perspective. Because components commonly must be shared across applications, or even across products, it is recommended that authors follow a standard method for selecting components. For more information, see Organizing Applications into Components.


Windows Installer Components

A component is a piece of the application or product to be installed. Examples of components include single files, a group of related files, COM objects, registration, registry keys, shortcuts, resources, libraries grouped into a directory, or shared pieces of code such as MFC or DAO.

The installer service installs or removes a component as a single coherent piece. It tracks every component by the respective component ID GUID specified in the ComponentId column of the Component table. Two components that share the same component ID are treated as multiple instances of the same component regardless of their actual content. Only a single instance of any component is installed on a user's computer. Several features or application may therefore share some components.

Because components are commonly shared, an author of an installation package must follow strict rules when specifying the components of a feature or application. This is essential for the correct operation of the Windows Installer reference counting mechanism. For more information, see Organizing Applications into Components.

In brief, these rules are:

  • Each component must be stored in a single folder.
  • No file, registry entry, shortcut, or other resources should ever be shipped as a member of more than one component. This applies across products, product versions, and companies.

For more information about using components, see

Installing a Missing Component

Installing Permanent Components, Files, Fonts, Registry Keys

Using Qualified Components

Using Transitive Components

Working with Features and Components

Checking the Installation of Features, Components, Files

Searching for a Broken Feature or Component

Publishing Products, Features, and Components


Windows Installer Features

A feature is a part of the application's total functionality that a user recognizes and may decide to install independently. For example, a feature could be a spell-checker, a thesaurus, or a group of clip-art. Hierarchical relationships of parent and child features commonly exist such that if a child feature is installed, the parent feature is automatically installed as well.

See the following for information about using features:

Requesting a Feature

Reinstalling a Feature or Application

Referencing Features in Merge Modules

Working with Features and Components

Checking the Installation of Features, Components, Files

Searching for a Broken Feature or Component

Publishing Products, Features, and Components


Installation Mechanism

There are two phases of installation process: acquisition and execution. If the installation is unsuccessful, a rollback phase may occur.

Acquisition

At the beginning of the acquisition phase, an application or a user instructs the installer to install a feature or an application. The installer then progresses through the actions specified in the sequence tables of the installation database. These actions query the installation database and generate a script that gives a step-by-step procedure for performing the installation.

Execution

During the execution phase, the installer passes the information to a process with elevated privileges and runs the script.

Rollback

If an installation is unsuccessful, the installer restores the original state of the computer. When the installer processes the installation script it simultaneously generates a rollback script. In addition to the rollback script, the installer saves a copy of every file it deletes during the installation. These files are kept in a hidden, system directory. Once the installation is complete, the rollback script and the saved files are deleted. For more information, see Rollback Installation.


Component Management

The Microsoft® Windows® Installer reduces the total cost of ownership (TCO) of your applications by increasing the ability of your customers to manage and maintain application components during setup and runtime. Because the installation database tracks which applications require a particular component, which files comprise each component, where each file is installed on the system, and where component sources are located, developers can author packages providing the following benefits.

  • Increased resiliency of applications. Use the installer to detect and reinstall damaged components without having to rerun setup. You can also use the installer to check the path of a component at runtime. This frees applications from dependency on static file paths which commonly differ between machines and can point to missing components. For more information, see Resiliency.
  • Install-On-Demand features. These features are not installed during the initial setup but are specified in the database to be installed just-in-time for use if required by the application in the future. Users do not need to rerun setup. For more information, see Installation-On-Demand.
  • Advertise shortcuts to features, applications, or entire products in the user interface without actually installing these. Users can install these on-demand by using the shortcuts. Users can also remove features, applications, or entire products on-demand. For more information, see Advertisement.
  • Customize installations to user's needs. An administrator can apply transforms to the database that tailor the installation for a particular group of users. For more information, see Customization.
  • Easier deployment of application updates. Use the installer to update your products. For more information, see Patching and Upgrades.
  • Display shortcuts to features that are run locally together with shortcuts to features run from a remote source. Because the installation database specifies the run context of each feature, visibly equivalent entry points can be presented to users if desire.
  • Keep usage metrics on features. Developers can provide an installation package that keeps a usage count of a feature by all client applications and removes components that are not being used.
  • Incorporate installations into applications. Developers can incorporate the component management capabilities of the installer into their applications by authoring an installation package and by using the Installer Functions in their application code. The following figure illustrates an application requesting the installation of a feature.


Advertisement

The Microsoft® Windows® Installer can advertise the availability of an application to users or other applications without actually installing the application. If an application is advertised, only the interfaces required for loading and launching the application are presented to the user or other applications. If a user or application activates an advertised interface the installer then proceeds to install the necessary components as described in Installation-On-Demand.

The two types of advertising are assigning and publishing. An application appears installed to a user when that application is assigned to the user. The Start menu contains the appropriate shortcuts, icons are displayed, files are associated with the application, and registry entries reflect the application's installation. When the user tries to open an assigned application it is installed upon demand.

For Microsoft® Windows® 2000, COM Class information is registered for assigned applications. This enables the installer to install the application upon the instantiation of an advertised Class. For more information, see Platform Support of Advertisement.

An application can only be published from a Windows 2000 Server. The published application is then installed by Windows 2000 through its file association or Multipurpose Internet Mail Extension (MIME) type. Publishing does not populate the user interface with any of the application's icons. Operating systems other than Windows 2000 cannot install a published application.


Installation-On-Demand

With traditional installation technology, it is necessary to exit an application and rerun setup to perform an installation task. This commonly occurred when a user wanted a feature or product not chosen during the first run of setup. This often made the process of product configuration inefficient because it required the user to anticipate the functionality required before they ever used the product.

Installation-on-demand makes it possible to offer functionality to users and applications in the absence of the files themselves. This notion is known as advertisement. The Microsoft® Windows® Installer has the capability of advertising functionality and to make installation-on-demand of application features or entire products possible. When a user or application activates an advertised feature or product, the installer proceeds with installation of the needed components. This shortens the configuration process because additional functionality can be accessed without having to exit and rerun another setup procedure.

When a product uses the installer, a user can choose at setup time which features or applications to install and which to advertise. Then if while running an application the user requests an advertised feature that has not yet been installed, the application calls the installer to enact a just-in-time feature level installation of the necessary files. If the user activates an advertised product that has not yet been installed, the operating system calls the installer to enact a just-in-time product level installation.

Advertisement and installation-on-demand can also facilitate system management by enabling administrators to designate applications as required or optional for different groups of users. There are two types of advertising known as "assigning" and "publishing." If an administrator assigns an application to a group, then these users can install the application on-demand. If, however, the administrator publishes the application to the group, no entry points appear to these users and installation-on-demand is only activated if another application activates the published application.


Resiliency

Resiliency is the ability of an application to recover gracefully from situations in which a vital component is missing, or has been replaced by an incompatible version. By authoring an installation package and using the Installer Functions, developers can use the Microsoft® Windows® Installer to produce resilient applications capable of recovering from such situations.

  • Use the installer's source list to increase the resiliency of applications that rely on network resources. For more information, see Source Resiliency.
  • Use the installer's API to check whether a vital feature, component, file, or file version is installed.
  • Use the installer's API to check the path to a component at runtime. This reduces your application's dependency on static file paths, which commonly differ between machines.
  • Use the installer to reinstall damaged shortcuts, registry entries, and other components without having to rerun setup.
  • Increase the resiliency of your product's installation by leaving the rollback capability of the installer enabled. For more information, see Rollback Installation.


Customization

Because the Microsoft® Windows® Installer keeps all information about the installation in a relational database, the installation of an application or product can be customized for particular user groups by applying transform operations to the package. Transforms can be used to encapsulate the various customizations of a base package required by different workgroups. For more information, see Merges and Transforms.

Multiple transforms of a base package can be applied on-the-fly during installation. This provides a mechanism for efficiently assigning customized installations to different groups of users. For example, this would be useful in organizations where the finance and staff support departments require different installations of a particular product. The product can be made available to everyone in the organization by an administrative installation of the base package to a single administrative installation point. Each work group can then automatically receive their appropriate customization by means of an on-the-fly transform when they install the product.


Administrative Installation

The Microsoft® Windows® Installer can perform an administrative installation of an application or product to a network for use by a workgroup. An administrative installation installs a source image of the application onto the network that is similar to a source image on a CD-ROM. Users in a workgroup who have access to this administrative image can then install the product from this source. A user must first install the product from the network to run the application. The user can choose to run-from-source when he installs and the installer uses most of the product's file directly from the network.

Administrators can run an administrative installation from the command line by using the /a command line option.

The ADMIN action is the top-level action used to initiate an administrative installation. When this action is executed the installer calls the actions in the AdminExecuteSequence and AdminUISequence tables to perform the administrative installation.

The AdminProperties property is a semicolon delimited list of properties that are set at the time of an administration installation. The installer uses these properties during a post administration installation of the application from the administrative image.

Users who do not have continuous access to the network may install an application from an administrative image and then at times have to rely on media, such as CD-ROM disks, as their backup source. In these cases the length of the file names in the administrative image and on the media must match. Both must use long file names or both must use short file names. For example, a CD-ROM that only supports short file names could provide both the original media for installing the administrative image and a backup source.

If the SHORTFILENAMES property is set during an administrative installation, this property may need to be set again by a user subsequently applying a patch to the administrative image. When using Windows Installer version 1.5 or later versions to apply the patch, the installer automatically sets the SHORTFILENAMES property if the administrative image uses short file names. With Windows Installer versions earlier than version 1.5, the user applying the patch must set the SHORTFILENAMES property.

If an administrator uses a package having a Word Count Summary Property of 2 or 3 to perform an administrative installation, users of the administrative image cannot automatically reinstall from the original media source. If the administrative image becomes unavailable, users who have installed from the administrative image are prevented from reverting to the original media.

The application of transforms during the creation of an administrative image has no valid effect. To make a customized version of a product available to a work group, apply the transform during the installation of the product from the administrative image.


Rollback Installation

When the Microsoft® Windows® Installer processes the installation script for the installation of a product or application, it simultaneously generates a rollback script and saves a copy of every file deleted during the installation. These files are kept in a hidden system directory and are automatically deleted once the installation is successfully completed. If however the installation is unsuccessful, the installer automatically performs a rollback installation that returns the system to its original state.

Automatic rollback of an unsuccessful installation is the default behavior of the installer. To disable rollback during an installation use one of the following:

  • DISABLEROLLBACK Property
  • PROMPTROLLBACKCOST Property
  • DisableRollback Action
  • DisableRollback
  • EnableRollback ControlEvent

Whenever rollback is disabled, the installer sets the RollbackDisabled property.

If an installation uses custom actions, additional authoring of the installation package is required to use rollback functionality. For more information, see Rollback Custom Actions.


Maintenance Installation

After an application has been successfully installed, the user may want to return to the installation to add or remove features. This is known as a maintenance installation.

Transforms that have been applied to an installation must be available during subsequent maintenance installations.


System Reboots

The Microsoft® Windows® Installer can determine when a reboot of the system is necessary and automatically prompt the user to reboot at the end of the installation. For example, the installer automatically prompts for a reboot if it needs to replace any files that are in use during the installation.

Installation package authors can schedule and suppress reboots by using standard actions in the sequence tables and by setting properties. The following actions and properties are used to handle system reboots.

Action, dialog, or property | Brief description
ForceReboot Action | Prompts the user for a reboot during the installation.
ScheduleReboot Action | Prompts the user for a reboot at the end of the installation.
REBOOT Property | Forces or suppresses certain automatic prompts for a system reboot.
REBOOTPROMPT Property | Suppresses the display of prompts for reboots to the user. Any needed reboots happen automatically.
AFTERREBOOT Property | Commonly used in a condition imposed on the ForceReboot Action.
InstallValidate Action | Displays the FilesInUse Dialog, if necessary, giving users the opportunity to shut down processes and avoid some system reboots.
FilesInUse Dialog | Gives users the opportunity to shut down processes to avoid some system reboots.
ReplacedInUseFiles Property | Set if the installer installs over a file in use. This property is used by custom actions to detect that a reboot is required.

With Windows Installer version 1.0, ERROR_INSTALL_SUSPEND is returned when the ForceReboot action is run and ERROR_SUCCESS is returned in other cases requiring a reboot to complete the installation.

With Windows Installer version 1.1, the installer returns the error code ERROR_INSTALL_SUSPEND whenever the ForceReboot action is run. It returns ERROR_SUCCESS_REBOOT_REQUIRED if a reboot is required before running the application, and it returns ERROR_SUCCESS_REBOOT_INITIATED if the installer has actually started a reboot. Note that because reboots are asynchronous, the reboot may actually occur before the error code is returned. ERROR_SUCCESS_REBOOT_INITIATED was not defined in the msi.h for installer version 1.0; it has a numeric value of 1641. For more information, see Error Codes.

Custom actions can force a prompt for reboot at the end of an installation by calling MsiSetMode. Custom actions can also check for a pending reboot prompt by calling MsiGetMode.

FilesInUse Dialog

The installer can determine when a reboot of the system is necessary and prompt the user with a request to reboot. Commonly, a system reboot is required because the installer is attempting to install a file that is currently being used. If the InstallValidate action detects the installation of a file in use it displays the FilesInUse Dialog.

If you expect the installer to display a FilesInUseDialog, but it does not, this may be due to one of the following reasons:

  • The files in use are not executables.
  • The installer is not actually trying to install those files.
  • The process holding those files is the process invoking the installation.
  • The process holding those files is one that does not have a window with a title associated with it.

See Logging of Reboot Requests.


Logging of Reboot Requests

If the InstallValidate action detects the installation of a file in use it displays the FilesInUse Dialog and logs the following information.

Info 1603. The file E:\testdb\Test\CustAct1.dll is being held in use
by the following process: Name: test, Id: 137, Window Title: 'Test'.

If the installer detects that it is about to overwrite a file that is in use, it logs the following information.

Info 1603. The file E:\testdb\Test\CustAct2.dll is being held in use.
Info 1903.Scheduling reboot operation: Deleting file [filename]. Must reboot to complete operation.

The [filename] token may actually contain a path to a file with an .rbf extension. In this case the .rbf file is actually the original file logged by the 1603 message which has been renamed to the .rbf file. The file that's in use is first renamed with an .rbf extension and then deleted.

To obtain more information about why the installer is attempting to overwrite this particular file, you can use the verbose logging option. Use the INSTALLLOGMODE_VERBOSE value in a call to MsiEnableLog or use the verbose output option of the Command Line Options. This logs the following information.

MSI (s) (D0:F0): File: E:\testdb\Test\CustAct2.dll;  Overwrite;
REINSTALLMODE specifies all files to be overwritten

The log will include a message such as "Existing file is a lower version" or "Existing file is corrupt (invalid checksum)"


System Policy

The installation behavior of the Microsoft® Windows® Installer can be configured by an administrator by using the Group Policy Editor (GPE), on Microsoft Windows® 2000 or by using the System Policy Editor on Windows 95, Windows 98, and Microsoft Windows NT®.

  • User Policies
  • Machine Policies


User Policies

The following user policies can be configured under

HKEY_CURRENT_USER\Software\Policies\Microsoft\Windows\Installer

Value name | Value data types | Description
AlwaysInstallElevated | REG_DWORD | If this value is set to "1" and the corresponding machine value is also set, the installer always installs with elevated privileges. Otherwise, the installer uses elevated privileges to install managed applications and uses the current user's privilege level for non-managed applications.
DisableMedia | REG_DWORD | If the DisableMedia policy is set to "1", users and administrators running a maintenance installation of one product are prevented from using the Browse Dialog to browse media sources, such as CD-ROM, for the sources of other installable products. Browsing for other products is prevented regardless of whether the installation is with elevated privileges. It is still possible for the user to reinstall the product from media if the user has a correctly labeled media source. This policy is not available with Windows Installer version 1.0.
DisableRollback | REG_DWORD | If this value is set to "1", the installer will not store rollback files during installation, disabling installation rollback. By default, rollback is enabled. Administrators are advised to not use this policy unless it is absolutely essential.
SearchOrder | REG_SZ | Order in which the installer searches the three different types of sources: "n" - network "m" - media (CD-ROM or DVD) "u" - URL (Uniform Resource Locator) For example, a value of "nmu" instructs the installer to search network sources first, media sources second, and URL sources last. Leaving out a letter removes the corresponding volume type from the search. Default order in absence of this value is network first, then media followed by URL.
TransformsAtSource | REG_DWORD | If this value exists and is set to "1"; the installer searches for transform files in the root of any network sources in the source list for the product. By default, transforms are stored in the Application Data folder of a user's profile. This policy is not available with Windows Installer version 1.1.


AlwaysInstallElevated

To always install a package with elevated (system) privileges, set the AlwaysInstallElevated value to "1" under both of the following registry keys.

HKEY_CURRENT_USER\Software\Policies\Microsoft\Windows\Installer

HKEY_LOCAL_MACHINE\Software\Policies\Microsoft\Windows\Installer

If the AlwaysInstallElevated value is not set to "1" under both of the above registry keys, the installer uses elevated privileges to install managed applications and uses the current user's privilege level for non-managed applications.

Registry Key

HKEY_CURRENT_USER\Software\Policies\Microsoft\Windows\Installer

HKEY_LOCAL_MACHINE\Software\Policies\Microsoft\Windows\Installer


DisableMedia

If this per-user system policy is set to "1", users and administrators running a maintenance installation of one product are prevented from using the Browse Dialog to browse media sources, such as CD-ROM, for the sources of other installable products. Browsing for other products is prevented regardless of whether the installation is done with elevated privileges. It is still possible for the user to reinstall the product from media if the user has a correctly labeled media source.

This policy not available with Windows Installer version 1.0.

Registry Key

HKEY_CURRENT_USER\Software\Policies\Microsoft\Windows\Installer

Remarks

Note that the DISABLEMEDIA property has a different effect than the DisableMedia policy. Setting the DisableMedia system policy, with Windows Installer version 1.1 or later, only disables browsing to media sources. Installations using Windows Installer version 1.1 should be secured by using the DisableMedia and DisableBrowse policies. Setting the DISABLEMEDIA property prevents the installer from registering any media source, such as a CD-ROM, as a valid source for the product. If browsing is enabled however, a user may still browse to a media source.

Administrators can secure a managed installation with Windows Installer version 1.0 by setting both the DISABLEMEDIA property and the DisableBrowse policy. This stops users from browsing to a media source.

See Also

Source Resiliency


DisableRollback

If this system policy is set to "1", the installer does not store rollback files during installation and disables installation rollback. By default, rollback is enabled. Administrators are advised to not use this policy unless it is absolutely essential. For more information, see Rollback Installation.

Registry Key

To disable rollback for per-user installations, set DisableRollback to "1" under the following registry key.

HKEY_CURRENT_USER\Software\Policies\Microsoft\Windows\Installer

To disable rollback for per-machine installations, set DisableRollback to "1" under the following registry key. This policy is not available with Windows Installer version 1.0.

HKEY_LOCAL_MACHINE\Software\Policies\Microsoft\Windows\Installer


SearchOrder

Setting this per-user system policy specifies the order in which the installer searches three types of sources. The types of sources are:

"n" - network

"m" - media (CD-ROM or DVD)

"u" - Uniform Resource Locator (URL)

For example, to search network sources first, media sources second, and URL sources last set this policy to a value of "nmu". To omit searching for a particular source type, leave out the corresponding letter from the value.

If SearchOrder is not set, the default search order is network, media, and then URL.

Registry Key

HKEY_CURRENT_USER\Software\Policies\Microsoft\Windows\Installer

See Also

Source Resiliency


TransformsAtSource

If this per-user system policy is set to "1"; the installer searches for transform files in the root of any network sources in the source list for the product. By default, transforms are stored in the Application Data folder of a user's profile.

Registry Key

HKEY_CURRENT_USER\Software\Policies\Microsoft\Windows\Installer

Remarks

Setting this property with Windows Installer version 1.0 is similar to setting the TRANSFORMSATSOURCE property except that the scope is different. Setting TransformsAtSource policy applies to all packages installed by a given user. Setting the TRANSFORMSATSOURCE property applies to the package regardless of the users.

This policy and property are not available with Windows Installer version 1.1. Windows Installer version 1.1 interprets the TransformsAtSource policy to be the same as the TransformsSecure policy.

See Also

Transforms


Machine Policies

The following machine policies can be configured under:

HKEY_LOCAL_MACHINE\Software\Policies\Microsoft\Windows\Installer

Value | Value data type | Description
AlwaysInstallElevated | REG_DWORD | If this value is set to "1" and the corresponding user value is also set, the installer always installs with elevated privileges. Otherwise, the installer uses elevated privileges to install managed applications and uses the current user's privilege level for non-managed applications.
AllowLockdownBrowse | REG_DWORD | If this policy value is set to "1", non-administrative users can browse for new sources while running an installation at elevated privileges. The default is that only administrators can browse for sources during an elevated installation. Setting this policy also enables non-administrative users to run programs at LocalSystem privileges during an elevated installation. This policy not available with Windows Installer version 1.0.
AllowLockdownMedia | REG_DWORD | If this policy value is set to "1", non-administrative users can use media sources, such as a CD-ROM, while running an installation at elevated privileges. The default is that only administrators can use media sources during an elevated installation. Setting this policy also enables non-administrative users to run programs at LocalSystem privileges during an elevated installation. This policy not available with Windows Installer version 1.0.
AllowLockdownPatch | REG_DWORD | If this policy value is set to "1", non-administrative users can apply Windows Installer patches to existing products while running an installation at elevated privileges. The default is that only administrators can patch existing products that were installed at elevated privileges. Setting this policy also enables non-administrative users to run programs at LocalSystem privileges during an elevated installation. This policy not available with Windows Installer version 1.0.
Debug | REG_DWORD | If this value exists and is set to "1", the installer writes common debugging messages to the debugger using the OutputDebugString function. If this value exists and is set to "2", the installer writes all valid debugging messages to the debugger using the OutputDebugString function. This policy is for debugging purposes only and may not be supported in future versions of Windows Installer.
DisableBrowse | REG_DWORD | If this value exists and is set to "1", users are prevented from browsing to locate installer sources. The "Use feature from:" combo box for direct input is locked and the "Browse..." button is disabled. See the source resiliency topic for more details on source browsing.
DisableMSI | REG_DWORD | If this value exists and is set to "2", the installer is always disabled for all applications. If this value is set to "1", the installer is disabled for non-managed applications but is still enabled for managed applications. If this value is set to "0", any other number, or is absent, the installer is always enabled.
DisablePatch | REG_DWORD | If this value is set to "1" the installer does not apply patches. This policy can be used to provide security in environments where patching must be restricted.
DisableRollback | REG_DWORD | If this value is set to "1", the installer does not store rollback files during installation, disabling installation rollback. By default, rollback is enabled. Administrators are advised to not use this policy unless it is absolutely essential. This policy is not available with Windows Installer version 1.0.
EnableAdminTSRemote | REG_DWORD | Setting this policy enables administrators to perform installations from Terminal Server client sessions. This policy is not available with Windows Installer version 1.0.
EnableUserControl | REG_DWORD | If this value is set to 1, then the installer can pass all public properties to the server side during a managed installation using elevated privileges. Setting this policy has the same effect as setting the EnableUserControl property.
Logging | REG_SZ | This policy is used only if logging has not been enabled by the "/L" command line option or MsiEnableLog. If policy is set in this case, a log file is created in the temp directory with the random name: MSI*.LOG. Specify the logging mode by setting the policy value to a string of characters. Use the same characters to specify logging mode policy as used by the '/L' command line option. See Command Line Options. Note that you cannot use "+" and "*" for the policy.
SafeForScripting | REG_DWORD | If this value is set to "1", users are not prompted when scripts use installer automation within a web page. This may be useful for web based tools but can allow silent installations of applications without user knowledge or consent.
TransformsSecure | REG_DWORD | Setting the TransformsSecure policy to 1 informs the installer that transforms are to be cached locally on the user's computer in a location where the user does not have write access. This policy is not available with Windows Installer version 1.0.


AllowLockdownBrowse

Setting the value of this per-machine system policy to "1" enables non-administrative users to use a Browse Dialog to locate sources of managed applications stored on media, such as CD-ROM. For more information, see Source Resiliency. The default on Windows Installer version 1.1 and later versions is that non-administrative users cannot browse sources of managed applications that are located that on media. For example, if this policy set, a non-administrative user may browse media sources of assigned or published applications or applications being installed for all users. Setting AllowLockdownBrowse also enables non-administrative users to run programs at LocalSystem privileges during an elevated installation.

This policy is only available with Windows Installer versions later than version 1.0. AllowLockdownBrowse is not available with Windows Installer version 1.0.

Registry Key

HKEY_LOCAL_MACHINE\Software\Policies\Microsoft\Windows\Installer

Remarks

Setting this policy also enables non-administrative users to run arbitrary programs at LocalSystem privileges if they have a Windows Installer package that installs or launches those programs. Note this policy is not available with Windows Installer version 1.0. Systems using version 1.0 of the installer should therefore be secured as described in Source Resiliency Policy - Windows Installer Version 1.0. For Windows NT version 4.0 using Windows Installer version 1.0, the possible security threat only applies to products that have been installed for all users of the computer.

DisableBrowse overrides AllowLockdownBrowse and prevents browsing even if AllowLockdownBrowse is set.

See Also

Source Resiliency, AllowLockdownMedia


AllowLockdownMedia

Setting the value of this per-machine system policy to "1", enables non-administrative users to install managed applications from sources stored on media, such as a CD-ROM. See Source Resiliency. The default on Windows Installer version 1.5 and later versions is that non-administrative users cannot install managed applications from a source located on media. For example, if this policy is set, a non-administrative user may use a media source to install assigned or published applications or applications being installed for all users. Setting this policy also enables non-administrative users to run programs at LocalSystem privileges during an elevated installation.

This policy is only available with Windows Installer versions later than version 1.0. AllowLockdownMedia is not available with Windows Installer version 1.0.

Registry Key

HKEY_LOCAL_MACHINE\Software\Policies\Microsoft\Windows\Installer

Remarks

Setting this policy also enables non-administrative users to run arbitrary programs at LocalSystem privileges if they have a Windows Installer package that installs or launches those programs. Note this policy is not available with Windows Installer version 1.0. Systems using version 1.0 of the installer should therefore be secured as described in Source Resiliency Policy - Windows Installer Version 1.0. With Windows NT version 4.0 using Windows Installer version 1.0, the possible security threat only applies to products that have been installed for all users of the computer.

On Windows Installer version 1.1, a non-administrative user is still capable of installing managed applications from sources located on a correctly labeled media. Systems using version 1.1 of the installer should therefore be secured as described in Source Resiliency Policy - Windows Installer Version 1.1.

See Also

Source Resiliency, AllowLockdownBrowse


AllowLockdownPatch

If this per-machine system policy is set to "1", non-administrative users can apply Windows Installer patches to existing products while running an installation at elevated privileges. The default is that only administrators can patch existing products that were installed at elevated privileges. Setting this policy also enables non-administrative users to run programs at LocalSystem privileges during an elevated installation.

This policy not available with Windows Installer version 1.0.

Registry Key

HKEY_LOCAL_MACHINE\Software\Policies\Microsoft\Windows\Installer

Remarks

Any user can apply a patch during a non-elevated installation. Setting this per-machine system policy to "1" gives non-administrative users the additional flexibility of applying patches to any product during an elevated installation. If this policy is not set, non-administrative users cannot apply a patch to assigned or published applications.

Setting this policy also enables non-administrative users to run arbitrary programs at LocalSystem privileges if they have a Windows Installer patch package that installs or launches those programs.

Note this policy is not available with Windows Installer version 1.0. Systems using version 1.0 of the installer should therefore be secured by setting DisablePatch policy. On Windows NT 4.0 using Windows Installer version 1.0, the possible security threat only applies to products that have been installed for all users of the computer.


Debug

If this per-machine system policy is set to "1", the installer writes common debugging messages to the debugger using the OutputDebugString function. If this value is set to "2", the installer writes all valid debugging messages to the debugger using the OutputDebugString function. This policy is for debugging purposes only and may not be supported in future versions of Windows Installer.

Registry Key

HKEY_LOCAL_MACHINE\Software\Policies\Microsoft\Windows\Installer


DisableBrowse

Setting the value of this per-machine system policy to "1" prevents non-administrative users from using a Browse Dialog to locate sources of managed applications stored on media, such as CD-ROM. The "Use feature from:" combo box for direct input is locked and the "Browse..." button is disabled. For more details on source browsing, see source resiliency.

DisableBrowse overrides AllowLockdownBrowse and prevents browsing even if AllowLockdownBrowse is set.

Registry Key

HKEY_LOCAL_MACHINE\Software\Policies\Microsoft\Windows\Installer

Remarks

Note that setting the DisableBrowse policy only disables the capability to browse to sources. In some cases non-administrative users may still be capable of installing managed applications from sources on correctly labeled media. For details of how to secure media sources of managed applications see Source Resiliency.


DisableMSI

If the value of this per-machine system policy is set to "2" the installer is always disabled for all applications.

If this policy value is set to "0", any other number, or is absent, the installer is always enabled.

If this policy value is set to "1", the installer is disabled for non-managed applications but is still enabled for managed applications. This setting does allow an application to be advertised to all users of a machine, but does not allow an application to be advertised to the current user.

Registry Key

HKEY_LOCAL_MACHINE\Software\Policies\Microsoft\Windows\Installer


DisablePatch

If this per-machine system policy is set to "1", the installer does not apply patches. This policy can be used to provide security in environments where patching must be restricted.

Registry Key

HKEY_LOCAL_MACHINE\Software\Policies\Microsoft\Windows\Installer


EnableAdminTSRemote

Setting this per-machine system policy enables administrators to perform installations from Terminal Server client sessions. If this policy is not set, administrators can only perform installations from the console. Non-administrative users can never do installs from client sessions. For more information, see Terminal Services in the Platform SDK.

Administrators can always do Administrative installations from a Terminal Server client session, or from the console, regardless of whether this policy is set.

Registry Key

HKEY_LOCAL_MACHINE\Software\Policies\Microsoft\Windows\Installer

Remarks

Note this policy is not available with Windows Installer version 1.0.


EnableUserControl

If this per-machine system policy is set to "1", then the installer can pass all public properties to the server side during a managed installation using elevated privileges. Setting this policy has the same effect as setting the EnableUserControl property.

Registry Key

HKEY_LOCAL_MACHINE\Software\Policies\Microsoft\Windows\Installer


Logging Policy

This per-machine system policy is used only if logging has not been enabled by the "/L" command line option or by MsiEnableLog. If the policy is set in this case, the installer creates a log file in the temp directory with the random name: MSI*.LOG. Specify the logging mode by setting the policy value to a string of characters. Use the same characters to specify logging mode policy as used by the "/L" command line option. Note that you cannot use "+" and "*" for the policy.

Registry Key

Set the value named Logging under the following registry key.

HKEY_LOCAL_MACHINE\Software\Policies\Microsoft\Windows\Installer


SafeForScripting

If this per-machine system policy is set to "1", the installer does not prompt users when scripts within a Web page use the installer's automation interface. This practice may be useful for Web-based tools. Note that setting this policy allows the installation of applications without user knowledge.

Registry Key

HKEY_LOCAL_MACHINE\Software\Policies\Microsoft\Windows\Installer


TransformsSecure

Setting the TransformsSecure policy to 1 informs the installer that transforms are to be cached locally on the user's computer in a location where the user does not have write access. Setting this property is the same as setting the TRANSFORMSSECURE property except the scope is different. Setting TransformsSecure policy applies to all packages installed to a given machine. Setting the TRANSFORMSSECURE property applies to the package regardless of the machine.

The purpose of this policy is to provide for secure transform storage with traveling users of Windows NT or Windows 2000. When this policy is set, a maintenance installation can only use the transform from the secured cache. In the event that the installer finds that the transform is missing on the local computer, the installer attempts to restore the transform. In order for the installer to restore the transform, the secure transform must reside at an authorized source in the installation package's source list. For more information, see Source Resiliency. The maintenance installation fails if the transform is unavailable or cannot be loaded.

Registry Key

HKEY_LOCAL_MACHINE\Software\Policies\Microsoft\Windows\Installer

Remarks

The TransformsSecure policy is not available with Windows Installer version 1.0.

Windows Installer version 1.1 interprets the TransformsAtSource policy to be the same as the TransformsSecure policy.


Source Resiliency

Applications that rely on network resources for installation-on-demand are susceptible to source failures if the source location should change for any reason or become damaged. The Microsoft® Windows® Installer provides source resiliency for features that are installed on-demand by using a source list. The source list contains the locations searched by the installer for installation packages. The entries in this list can be network locations, Uniform Resource Locators (URLs), or compact discs. If one of these sources fails, the installer can quickly and seamlessly try the next.

The application developer does not need to incorporate any special information into the installer package to ensure source resiliency. Once the application is installed, the installer has the behavior of adding the last successfully used source as an entry in the source list. By default, this source is the location from which the installer package is initially installed, and is the same as the SourceDir property.

A system administrator can change the source list by applying a transform or by changing the SOURCELIST property from the command line or in the Property table.

The installer begins searching for a source by checking the most recently used source location in the source list. If this search fails, the installer searches the list of network sources, then media sources, and finally URL sources. System administrators can change this search order using the SearchOrder system policy. If these searches fail, the installer may present a Browse Dialog so that the user search for the source manually. The browse dialog cannot be displayed if the user interface level is set to None. For details, see User Interface Levels.

Commonly, the installer should only display a browse dialog box if the current user is an administrator or if the installation does not require elevated privileges. An administrator can control the display of the browse dialog to users with the DisableBrowse and AllowLockDownBrowse policies. An administrator also controls whether users can install applications from sources located on media by using the DisableMedia and AllowLockDownMedia policies. The use of these policies depends on the Windows Installer version. For details, see the following:

  • Source Resiliency Policy - Windows Installer Version 1.0
  • Source Resiliency Policy - Windows Installer Version 1.1
  • Source Resiliency Policy - Windows Installer Version 1.5


Source Resiliency Policy - Windows Installer Version 1.0

The installer begins searching for a source by checking the most recently used source location in the source list, then the list of network sources, then media sources, and finally URL sources. For details, see Source Resiliency. If these searches fail, the installer may present a Browse Dialog box so that the user can search for the source manually. The browse dialog box cannot be displayed if the user interface levels is set to None. An administrator can control the display of the browse dialog to users by setting system policy.

Because Windows Installer version 1.0 includes removable media drives on all source lists, administrators using Windows Installer version 1.0 should secure managed applications by setting the DISABLEMEDIA property, the DisableBrowse policy, and by omitting the "m" option from the SearchOrder policy. This prevents non-administrators from using the browse dialog to search for sources located on media, such as a CD-ROM, and also prevents non-administrators from using these sources to install managed applications. Note that setting the DISABLEMEDIA property prevents the installer from registering any sources located on media. This prevents first time installation from sources located on media.

The following table summarizes the use of these system policies in Windows Installer version 1.0.

System Policy | Non-Administrator Users Non-Managed Application | Non-Administrator Users Managed Application | Administrators Managed Application Non-Managed Application
Default | Users can install unmanaged applications using sources located on media. Users can browse media for the sources of unmanaged applications. | Users can install managed applications using sources located on media. Users can browse media for the sources of managed applications. | Administrators can install applications using sources located on media. Administrators can browse media for the sources of applications.
DisAbleBrowse DISABLEMEDIA SearchOrder omits the "m" parameter. | Users cannot install unmanaged applications using sources located on media. Users cannot browse media for the sources of unmanaged applications. | Users cannot install managed applications using sources located on media. Users cannot browse media for the sources of managed applications. | Administrators cannot install applications using sources located on media. Administrators cannot browse media for the sources of applications.

See Also

Source Resiliency


Source Resiliency Policy - Windows Installer Version 1.1

The installer begins searching for a source by checking the most recently used source location in the source list, then the list of network sources, then media sources, and finally URL sources. For more information, see Source Resiliency. If the search fails, the installer presents a Browse Dialog enabling the user to search for the source manually. The browse dialog cannot be displayed if the user interface levels is set to None. An administrator controls the display of the browse dialog to users by setting system policy.

With Windows Installer version 1.1, administrators should secure managed applications by setting the DisableMedia policy, the DisableBrowse policy, and by omitting the "m" option from the SearchOrder policy. This prevents non-administrators from using the browse dialog to search for sources located on media, and prevents non-administrators from using these sources to install managed applications. An administrator can enable a non-administrator to browse or install managed applications from media by using the AllowLockdownBrowse and AllowLockdownMedia policies. Note that setting the DisableMedia policy does not prevent first-time installation from sources located on media, it only prevents users from installing from media sources during maintenance installations.

The following table summarizes the use of these system policies in Windows Installer version 1.1.

System Policy | Non-Administrator User Non-Managed Application | Non-Administrator User Managed Application | Administrator Managed Application Non-Managed Application
AllowLockdownBrowse | Users can install unmanaged applications using sources located on media. Users can browse media for the sources of unmanaged applications. | Users cannot install managed applications using sources located on media. Users can browse media for the sources of managed applications. | Administrators can install applications using sources located on media. Administrators can browse media for the sources of applications.
AllowLockdownMedia | Users can install unmanaged applications using sources located on media. Users can browse media for the sources of unmanaged applications. | Users can install managed applications using sources located on media. Users can not browse media for the sources of managed applications. | Administrators can install applications using sources located on media. Administrators can browse media for the sources of applications.
Default | Users can install unmanaged applications using sources located on media. Users can browse media for the sources of unmanaged applications. | Users can install managed applications using sources located on media. Users can browse media for the sources of managed applications. | Administrators can install applications using sources located on media. Administrators can browse media for the sources of applications.
DisAbleBrowse SearchOrder omits the "m" parameter. | Users can install unmanaged applications using sources located on media. Users cannot browse media for the sources of unmanaged applications. | Users cannot install managed applications using sources located on media. Users cannot browse media for the sources of managed applications. . | Administrators can install applications using sources located on media. Administrators cannot browse media for the sources of applications.
DisAbleMedia SearchOrder omits the "m" parameter. | Users cannot install unmanaged applications using sources located on media. Users can browse media for the sources of unmanaged applications. | Users cannot install managed applications using sources located on media. Users cannot browse media for the sources of managed applications. | Administrators cannot install applications using sources located on media. Administrators can browse media for the sources of applications.

See Also

Source Resiliency


Source Resiliency Policy - Windows Installer Version 1.5

The installer begins searching for a source by checking the most recently used source location in the source list, then the list of network sources, then media sources, and finally URL sources. For more information, see Source Resiliency. If the search fails, the installer may present a Browse Dialog enabling the user to search for the source manually. The browse dialog cannot be displayed if the user interface levels is set to None. An administrator controls the display of the browse dialog to users by setting system policy.

With Windows Installer version 1.5, non-administrators by default cannot use the browse dialog to locate managed application sources on media and cannot install managed applications. An administrator enables a non-administrator to browse or install managed applications from media by using the AllowLockdownBrowse and AllowLockdownMedia policies. An administrator disables the capability to browse or install applications from media by using the DisAbleBrowse and DisAbleMedia policies.

The following table summarizes the use of these system policies in Windows Installer version 1.5.

 | Non-Administrator User Non-Managed Application | Non-Administrator User Managed Application | Administrator Managed Application Non-Managed Application
AllowLockdownBrowse | Users can install unmanaged applications using sources located on media. Users can browse media for the sources of unmanaged applications. | Users cannot install managed applications using sources located on media. Users can browse media for the sources of managed applications. | Administrators can install applications using sources located on media. Administrators can browse media for the sources of applications.
AllowLockdownMedia | Users can install unmanaged applications using sources located on media. Users can browse media for the sources of unmanaged applications. | Users can install managed applications using sources located on media. Users can not browse media for the sources of managed applications. | Administrators can install applications using sources located on media. Administrators can browse media for the sources of applications.
Default | Users can install unmanaged applications using sources located on media. Users can browse media for the sources of unmanaged applications. | Users cannot install managed applications using sources located on media. Users cannot browse media for the sources of managed applications. | Administrators can install applications using sources located on media. Administrators can browse media for the sources of applications.
DisAbleBrowse | Users can install unmanaged applications using sources located on media. Users cannot browse media for the sources of unmanaged applications. | Users cannot install managed applications using sources located on media. Users cannot browse media for the sources of managed applications. . | Administrators can install applications using sources located on media. Administrators cannot browse media for the sources of applications.
DisAbleMedia | Users cannot install unmanaged applications using sources located on media. Users can browse media for the sources of unmanaged applications. | Users cannot install managed applications using sources located on media. Users cannot browse media for the sources of managed applications. | Administrators cannot install applications using sources located on media. Administrators can browse media for the sources of applications.

See Also

Source Resiliency


Windows File Protection on Windows 2000

The Windows Installer adheres to Windows File Protection (WFP) when installing essential system files on Microsoft® Windows® 2000. If a protected system file is modified by an unattended installation of an application, WFP restores the file to the verified file version. For more information, see Windows File Protection in the Platform SDK.

The Windows Installer never attempts to install or replace a protected file. When the InstallFiles action or any other action scheduled before InstallFiles attempts to install a file protected on Windows 2000, the installer calls WFP with a request to install or replace the protected file. The installer requests the file installation from WFP immediately after executing the InstallFiles action. Windows File Protection installs or replaces the file on the user's system with a cached version of the protected file. Note that this does not guarantee that the version of the file installed from the cache is the version required by the application. After WFP has installed the file, the installer determines whether this version matches the version in the package. If the file version in the package is greater than the installed version, the installer informs the user that it cannot update the system and that an update of the operating system may be required for the application.

If any action sequenced after InstallFiles attempts to install or replace a protected file not already installed on the system, the installer cannot call WFP to install the file. In this case, the installer informs the user that it cannot update the system and that an update of the operating system may be required for the application.

The installer also checks with Windows File Protection when removing files and never attempts to remove protected system files.

Component Key Files Protected by Windows File Protection

When the installer attempts to install a component's key file on Windows 2000, it first calls Windows File Protection to determine if the key file is protected. When the key file of a component is protected by WFP, and that key file is already installed, the installer updates the component only if the version of the key file in the package is greater than the installed version. If the installation package specifies that a component be installed, and the key file of the is not currently installed, then regardless of whether the key file is protected the installer installs the component. Once any component having a key file protected by WFP is installed, it is permanently installed, and the installer never removes or replaces the component.

For information on Windows File Protection with Microsoft® Windows® Millennium Edition, see Windows File Protection on Windows Millennium Edition.


Windows File Protection on Windows Millennium Edition

Support for Windows File Protection on Microsoft® Windows® Millennium Edition (Windows Me) is provided with Windows Installer version 1.2. Windows Me implements its own version of system file protection using catalogs that describe protected files. To completely protect a file on Windows Me, the file must be listed by Windows File Protection and there must be a catalog with version information. To install a protected file, update the version information for the file with a catalog. Windows File Protection catalogs are provided to developers to enable their applications to update system components.

The InstallSFPCatalogFile action queries the Component table, File table, FileSFPCatalog table, and SFPCatalog table for catalogs and files. Each protected file in a catalog that can be installed separately should be put into a separate component. A catalog is associated with a protected file and is installed only if the component controlling the file is set for local installation or is already locally installed and is being repaired. The msidbComponentAttributesPermanent bit flag must be included for the component in the Attributes column of the Component Table. This prevents the removal of the catalog and protected file if the component is subsequently removed. The entry in the KeyPath column of the Component Table must exactly match the path specified by the provider of the Windows File Protection catalog. If the paths do not match, the file is not protected.

The InstallSFPCatalogFile action, FileSFPCatalog table, and SFPCatalog table are not available with Windows Installer versions 1.0 or 1.1.

For more information about Windows File Protection, see Windows File Protection in the Platform SDK. For information about using Windows File Protection with Windows 2000 see Windows File Protection on Windows 2000.


File Versioning Rules

At the core of any installer is the actual installation of files. But determining whether to install a file is a complex process. At the highest level, making the determination depends on whether the component to which a file belongs is marked for installation. Once the determination is made that a file should be copied, the process is complicated if another file with the same name exists in the target folder. In such situations, making the determination requires a set of rules involving the following properties:

  • Version
  • Date
  • Language

The installer only uses these rules when trying to install a file to a location that already contains a file with the same name. In this case, the Microsoft® Windows® Installer uses the following rules to determine whether to install.

Highest Version Wins — All other things being equal, the file with the highest version wins, even if the file on the machine has the highest version.

Versioned Files Win — All other things being equal, a versioned file gets installed over a non-versioned file.

Favor Product Language — All other things being equal, if the file being installed has a different language than the file on the machine, favor the file with the language that matches the product being installed. Language neutral files are treated as just another language so the product being installed is favored again.

Mismatched Multiple Languages — All other things being equal, after factoring out any common languages between the file being installed and the file on the machine, any remaining languages are favored according to what is needed by the product being installed.

Preserve Superset Languages — All other things being equal, preserve the file that supports multiple languages regardless of whether it is already on the machine or is being installed.

Non-versioned Files Are User Data — All other things being equal, if the Modified date is later than the Create date for the file on the machine, do not install the file because user customizations would be wiped out. If the Modified and Create dates are the same, install the file. If the Create date is later than the Modified date, the file is considered unmodified, install the file.

Non-versioned Files Using Companion — All other things being equal, a non-versioned file that is associated with a versioned file using the companion mechanism abides by the rules for the versioned file. The only exception is if the versioned file on the machine and the versioned file being installed have the same version and language but the companion file is missing on the machine. In this case the companion file being installed is used even though the versioned file on the machine is used.

Rules Are Global — The rules for determining when to install a file reside in one place within the installer and are global, meaning they apply to all files equally.

For examples of the format used for file versions, see the Version data type. For more specific information, see Replacing Existing Files or Default File Versioning.


Default File Versioning

The flow diagrams in the following sections illustrate the default file versioning rules used when the key file of a component being installed has the same name as a file already installed in the target location. Default file versioning is also illustrated in Replacing Existing Files.

Note that with Windows Installer version 1.5, file hashing is available to optimize the copying of files. For details, see MsiGetFileHash and the MsiFileHash table.

  • Both Files Have a Version
  • Neither File Has a Version
  • Neither File Has a Version with File Hash Check
  • One File Has a Version


Both Files Have a Version

If the key file of a component being installed (copy-A) has the same name as a file already installed in the target location (copy-B), the installer compares the version number, date, and language of the two files.

If both files have a version number, the installer uses the logic illustrated by the following flow diagram to determine whether to replace all of the installed files belonging to the component. Because the installer only installs entire components, if the installed key file is replaced then all the component's files are replaced.

Note that this diagram illustrates the default File Versioning Rules, which can be overridden by setting the REINSTALLMODE property. The default value of the REINSTALLMODE property is "omus".

The previous diagram can also be used with files with no language specified. If copy-A has a specified language and copy-B has no specified language, copy-B is replaced with copy-A. If copy-A and copy-B both have no language specified, then copy-B is not replaced.

See examples of default file versioning in Replacing Existing Files.

  • Neither File Has a Version
  • Neither File Has a Version with File Hash Check
  • One File Has a Version


Neither File Has a Version

If the key file of a component being installed (copy-A) has the same name as a file already installed in the target location (copy-B), the installer compares the version number, date, and language of the two files.

If neither file has a version number, the installer uses the logic illustrated by the following flow diagram to determine whether to replace all of the installed files belonging to the component. Because the installer only installs entire components, if the installed key file is replaced then all the component's files are replaced.

Note that this diagram illustrates the default File Versioning Rules, which can be overridden by setting the REINSTALLMODE property. The default value of the REINSTALLMODE property is "omus".

See the examples of default file versioning in Replacing Existing Files.

  • Both Files Have a Version
  • Neither File Has a Version with File Hash Check
  • One File Has a Version


Neither File Has a Version with File Hash Check

File hashing is available with Windows Installer version 1.5 and later. For more information, see MsiGetFileHash and the MsiFileHash table.

If the key file of a component being installed (copy-A) has the same name as a file already installed in the target location (copy-B), the installer compares the version number, date, and language of the two files.

If neither file has a version number, the installer uses the logic illustrated by the following flow diagram to determine whether to replace all of the installed files belonging to the component. Because the installer only installs entire components, if the installed key file is replaced then all the component's files are replaced.

Note that this diagram illustrates the default File Versioning Rules, which can be overridden by setting the REINSTALLMODE property. The default value of the REINSTALLMODE property is "omus".

See the examples of default file versioning in Replacing Existing Files.

  • Both Files Have a Version
  • Neither File Has a Version
  • One File Has a Version


One File Has a Version

If the key file of a component being installed (copy-A) has the same name as a file already installed in the target location (copy-B), the installer compares the version number, date, and language of the two files.

If only one of the files has a version number, the installer uses the logic illustrated by the following flow diagram to determine whether to replace all of the installed files belonging to the component. Because the installer only installs entire components, if the installed key file is replaced, then all the component's files are replaced.

Note that this diagram illustrates the default File Versioning Rules, which can be overridden by setting the REINSTALLMODE property. The default value of the REINSTALLMODE property is "omus".

See the examples of default file versioning in Replacing Existing Files.

  • Both Files Have a Version
  • Neither File Has a Version
  • Neither File Has a Version with File Hash Check


Product Codes

The product code is a GUID that is the principal identification of an application or product. For more information, see the ProductCode property. If significant changes are made to a product then the product code should also be changed to reflect this. It is not however a requirement that the product code be changed if the changes to the product are relatively minor.

The 32-bit and 64-bit versions of an application's package must have different product codes. If any 32-bit component of an application is recompiled into a 64-bit component, a new product code must be assigned.

If a server exposed in the PublishComponent Table is recompiled from 32-bits to 64-bits, the GUID in this table may also need to be changed so that 32-bit and 64-bit clients can identify the appropriate qualified component category. In this case, the product code must also be changed.

Note that letters in product code GUIDs must be uppercase. Utilities such as GUIDGEN generate GUIDs containing lowercase letters. The lowercase letters in these GUIDs must be changed to uppercase to be used as a product code or package code For more information, see Changing the Product Code.

The package code is a GUID identifying a particular Microsoft® Windows® Installer package. The package code associates an .msi file with an application or product and can also be used for the verification of sources. The product and package codes are not interchangeable. No two non-identical .msi files should ever have the same package code. Although it is common to ship an application that has the same package code and product code, the two values can diverge as the application is updated. For more information, see Package Codes.


Package Codes

The package code is a GUID identifying a particular Microsoft® Windows® Installer package. The package code associates an .msi file with an application or product and can also be used for the verification of sources. The product and package codes are not interchangeable. For details, see Product Codes.

No two non-identical .msi files should ever have the same package code. It is important to change the package code because it is the primary identifier used by the installer to search for and validate the correct package for a given installation. If a package is changed without changing the package code, the installer may not use the newer package if both are still accessible to the installer.

The package code is stored in the Revision Number Summary Property of the Summary Information Stream. Note that letters in product code and package code GUIDs must be uppercase. Utilities such as GUIDGEN generate GUIDs containing lowercase letters. The lowercase letters in these GUIDs must be changed to uppercase to be used as a product code or package code.

Although it is common to ship an application that has the same package code and product code, the two values can diverge as the application is updated. For example, including a new file with the application would require updating the installation database to install the file. If the changes are minor a developer may choose not to change the product code, however, a different .msi file is needed to install the new file and so the package code must be incremented. Conversely, a single package can be used to install more than one product. For example, the installation of a package without a language transform could install the English version of the application and the installation of the same package with a language transform could install the French version. The transform is distinct from the .msi file that determines the package code. The English and French versions could have different product codes and the same package code because they are both installed with the same .msi file.


Merges and Transforms

The Microsoft® Windows® Installer keeps all information about the installation in a relational database. You can modify this database, and therefore the installation, by using transforms and merges.

Transforms

A transform adds or replaces elements in the original database. For example, a transform can change all the text in an application's user interface from French to English.

Primary uses for transforms include:

  • Customization of base installation packages for particular groups of users.

    Transforms can be used to encapsulate the various customizations of a single base package that are required by different groups of users. For example, this is useful in organizations where the finance and staff support departments require different installations of a particular product. A product's base package can be available to everyone at one administrative installation point with the appropriate customizations distributed to each group of users separately.

  • Synchronization of applications across languages.

    Transforms are useful for keeping packages authored at widely separated locations synchronized during authoring. For example, if an upgrade is first developed for an English version of an application that exists in English and French, a transform can be applied to the upgraded English version that converts it into an upgraded French version.

    Multiple transforms can be applied to a base package and then applied on-the-fly during installation. This extends the capabilities of the installer to create custom packages and provides a mechanism for efficiently assigning the most appropriate installations to different groups of users.

  • Patching applications.

    Transforms can be used to apply a minor fix to an application that does not warrant a major upgrade. For more information about patches, see Patch Packages.

Merges

A merge combines two databases into a one database, and adds, rather than replaces, information. If the same information exists in both databases, a merge conflict occurs. Merges are useful to development teams because they allow a large application to be divided into parts that can be recombined later. For example, the database elements for the installation of a new component can be developed separately and later merged into the main installation database. For more information, see Merge Modules.

A development team might apply a merge operation in the following way:

  1. Separate into groups and work simultaneously on different components of a large application.
  2. Each development group the populates a database with the installation information for its own component, without being concerned with the other components of the application.
  3. After the development of a component is complete, that component's database can be merged into the main installation database for the entire application.


Qualified Components

A qualified component is a method of single-level indirection, similar to a pointer. Qualified components are primarily used to group components with parallel functionality into categories. For example, if you have 30 components listed in the Component table that are the same Microsoft® Word fax template localized into 30 languages, you can group these together into a category of qualified components by using the PublishComponent table.

Qualified components are entered in the Component table in the same way as ordinary components. Every component must have a unique component ID GUID and component identifier specified in the Component table. In addition, qualified components are associated with a category GUID and a text-string qualifier in the PublishComponent table. Qualified components are referenced by the category GUID and the qualifier, which just points to the ordinary component in the Component table.

For example, a qualified component ID GUID can point to different language versions of a resource DLL. In this case, the group of localized resource DLLs comprises the category and the numeric locale identifiers (LCID) strings are commonly used as the qualifiers. A developer could author an installation package that uses these qualified components to do the following.

  • Find the path to a particular language version of the resource DLL using MsiProvideQualifiedComponent or MsiProvideQualifiedComponentEx and install the resource.
  • Determine all the language versions of the resource DLL that are present by calling MsiEnumComponentQualifiers.
  • Prepare the application to support additional languages. A future language pack for the application can use the qualified component to add more language versions of the resource DLL.

For more information, see Using Qualified Components.


Logging

The Microsoft® Windows® Installer records errors and events in its own error log and the Event Log. The diagnostic information the installer writes to the these logs can help users and administrators understand the cause of a failed installations.

  • Normal Logging
  • Event Logging

See Also

Logging of Action Return Values, Logging of Reboot Requests, Checking the Installation of Features, Components, Files


Normal Logging

The installer records errors and events in its own error log. The type of logging performed by the installer is determined by setting the logging mode. Logging is enabled and the mode can be set by three methods:

  • Use MsiEnableLog or the EnableLog Method.
  • Use the /L option with Msiexec.exe. For details, see Command Line Options.
  • Use the Logging policy. For more information, see System Policy.


Event Logging

Event logging in Windows NT/Windows 2000 provides a standard, centralized way for applications (and the operating system) to record important software and hardware events. The event-logging service stores events from various sources in a single collection called an event log. Windows NT/Windows 2000 also supplies Event Viewer for viewing the logs, and a programming interface for examining the logs. For more information, see Event Logging.

The installer also writes entries into the Event Log. These record events such as following:

  • Success or failure of the installation, removal, or repair of a product.
  • Errors that occur during product configuration.
  • Detection of corrupted configuration data.

If a large amount of information is written the Event Log file can become full and the installer displays a message, "The Application log file is full."

Note there is no built-in Event Log on Windows 95 or Windows 98. On these systems, the installer logs the same event information into a file in the %temp% folder called Msievent.log. For more information, see Checking for the Installation of Features, Components, or Files.

The installer may write the following entries in the event log.

Message | Remarks
Product [2] – Installation operation completed successfully | Informational message that the installation of the product was successful.
Product [2] – Installation operation failed | Error message that the installation of the product failed.
Windows Installer proxy information not registered correctly | Error message that proxy information was not registered correctly.
Failed to connect to server. Error: %d | Informational message that the installation failed to connect to server.
{Unhandled exception report} | Error message for an unhandled exception, this is the report.
Detection of product '%1', feature '%2' failed during request for component '%3' | A warning message. For details, see Searching For a Broken Feature or Component.
Unexpected or missing value (name: '%1', value: '%2') in key '%3' | Error message that there was an unexpected or missing value.
Unexpected or missing subkey '%1' in key '%2' | Error message that there was an unexpected or missing subkey.
Detection of product '%1', feature '%2', component '%3' failed | A warning message. See also Searching For a Broken Feature or Component.
Install operation initiated a reboot | Informational message that the installation initiated a reboot of the system.


Logging of Action Return Values

The installer writes the following values into the log when an action returns the these error codes. For the entire list of error codes returned by the Windows Installer function calls, MsiExec.exe, and InstMsi.exe see Error Codes.

.Error Code | Values returned by function calls MsiExec.exe, and InstMsi.exe | Values that appear in the Log. | Description
ERROR_FUNCTION_NOT_CALLED | 1626 | 0 | Function could not be executed.
ERROR_SUCCESS | 0 | 1 | Action completed successfully.
ERROR_INSTALL_USEREXIT | 1602 | 2 | User canceled installation.
ERROR_INSTALL_FAILURE | 1603 | 3 | Fatal error.
ERROR_INSTALL_SUSPEND | 1604 | 4 | Installation suspended, incomplete.
ERROR_SUCCESS | 0 | 5 | Action completed successfully.
ERROR_INVALID_HANDLE_STATE | 1609 | 6 | Handle is in an invalid state.
ERROR_INVALID_DATA | 1626 | 7 | The data is invalid.

See also

Logging


Companion Files

The installation state of a companion file depends not on its own file versioning information, but on the versioning of its companion parent. To specify a companion file, the primary key of the companion parent in the File table must be authored into the Version column of the record for the companion.

In the following example, FileA is the companion parent and FileB is the companion file.

File Table (partial)

File | Version
FileA | 1.0.0.0
FileB | FileA

In this example, the installation state of FileB depends on the File Versioning Rules and the versioning information for FileA. If the installer determines that the version of FileA in the package should be installed over an older version of FileA that already exists on the user's computer, it will also install FileB from the package regardless of the version of any installed FileB.

Note that a file that is the key path for its component must not be a companion file. This would result in the versioning logic of the key path file being determined by the companion parent file.


Isolated Components

Authors of installation packages can specify that the installer copy the shared files (commonly shared DLLs) of an application into the application's folder rather than to a shared location. This private set of files (DLLs) are then used only by the application. Isolating the application together with its shared components in this manner has the following advantages:

  • The application always uses the versions of shared files with which it was deployed.
  • Installing the application does not overwrite other versions of the shared files by other applications.
  • Subsequent installations of other applications using different versions of the shared files cannot overwrite the files used by this application.

Because the current implementation of COM keeps a single full path in the registry for each CLSID/Context pair, it forces all applications to use the same version of a shared DLL. To enable an application to keep a private copy of a COM server, the system loader in Windows 98 and Windows 2000 checks for the presence of a .LOCAL file in the application's folder. If the system loader detects a .LOCAL file, it alters its search logic to prefer DLLs located in the same folder as the application.

When Windows Installer version 1.1 executes the IsolateComponents action it copies the files of the component (commonly a shared DLL) specified in the Component_Shared column of the IsolatedComponent table into the same folder as the component (commonly an .exe) specified in the Component_Application column. The installer creates a file in this directory, zero bytes in length, having the short filename name of the key file for Component_Application (typically the name is the same as the application's .exe) appended with .LOCAL. The installer uses the registration for the component in its shared location and does not write any registration information for the copy of the component in the private location. The IsolatedComponent action and table are not available with Windows Installer version 1.0.

For more information, see:

Installation of Isolated Components

Reinstallation of Isolated Components

Removal of Isolated Components

Using Isolated Components


Installation of Isolated Components

Windows Installer version 1.1 does the following during installation of an application when the package contains isolated components. Commonly, Component_Shared is a DLL that is shared by Component_Application and other client executables.

Installation

  • Copy the files of Component_Shared into the same folder as Component_Application only if Component_Application is also being installed.
  • Create a zero-byte file with the short filename of the key file of Component_Application. Locate this file in the same folder as Component_Application. Append the extension .LOCAL to this filename.
  • Increment the SharedDLL refcount if the msidbComponentAttributesSharedDllRefCount bit is set in the Attributes column of the Component table.
  • Register Component_Application as a client of Component_Shared and register a key path pointing to the shared location of Component_Shared.
  • Install all the resources of Component_Application as usual.

If Component_Shared, or if its key file, is already installed on the computer:

  • Copy no files to the shared location of Component_Shared.

If Component_Shared or its key file is not yet installed on the computer:

  • Copy the files of Component_Shared to the shared location.
  • Process all install actions for Component_Shared.
  • If Component_Shared is a COM component, register the full COM path such that the syntaxes [$Component] and [#FileKey] point to the shared location of Component_Shared.


Reinstallation of Isolated Components

Windows Installer version 1.1 does the following during reinstallation of an application when the package contains isolated components. Commonly, Component_Shared is a DLL that is shared by Component_Application and other client executables.

Reinstallation

  • Reinstall the files of Component_Shared into the same folder as Component_Application only if Component_Application is also being reinstalled.
  • Do not increment the client list of Component_Shared and do not increment the SharedDLL count.
  • Recreate the zero-byte file with the short filename of the key file of Component_Application. This file must be located in the same folder as Component_Application and have the extension .LOCAL.
  • Reinstall all the resources of Component_Application as usual.

If the SharedDLL refcount for Component_Shared is more than 1, or if other products remain on the client list of Component_Shared:

  • Reinstall no files to the shared location of Component_Shared.

If the SharedDLL refcount for Component_Shared equals 1, or if there are no other remaining clients of Component_Shared:

  • Reinstall the files of Component_Shared into the shared location using the File Versioning Rules.
  • Process all reinstall actions for Component_Shared.
  • If Component_Shared is a COM component, register the full COM path such that the installer syntaxes [$Component] and [#FileKey] point to the shared location of Component_Shared.


Removal of Isolated Components

Windows Installer version 1.1 does the following during the removal of an application when the package contains isolated components. Commonly, Component_Shared is a DLL that is shared by Component_Application and other client executables.

Uninstall

  • Remove the files of Component_Shared from the folder containing Component_Application only if Component_Application is also being removed.
  • If msidbComponentAttributesSharedDllRefCount is set in the Component table decrement the SharedDLL refcount.
  • Remove the .LOCAL zero-byte file from the folder containing Component_Application.
  • Remove Component_Application from the client list of Component_Shared.
  • Remove all the resources of Component_Application as usual.

If there are other products remaining on the client list of Component_Shared:

  • Remove no files from the shared location of Component_Shared.

If the SharedDLL refcount for Component_Shared is 0 after being decremented, or if there are no other remaining clients of Component_Shared:

  • Remove the files of Component_Shared from the shared location.
  • Process all uninstall actions with respect to this component.


Per-Machine Installations

Per-Machine installation of an application means the application is available for all users of a computer. It also means:

  • Shortcuts are installed to the All Users profile.
  • COM registration is always written to HKLM\Software\Classes.
  • On Microsoft® Windows® 2000 and Microsoft® Windows NT®, always run at elevated privileges.
  • Icons and transforms are stored in %WINDOWS%\Installer\{ProductCode}.
  • The installer sets the following properties to the following values during per-machine installations.
Property | Description | CSIDL
DesktopFolder property | Full path to the Desktop Folder for All Users. Exists on Windows 2000 and Windows NT. | CSIDL_COMMON_DESKTOPDIRECTORY
ProgramMenuFolder property | Full path to the Program Menu Folder for All Users. Exists on Windows 2000 and Windows NT. | CSIDL_COMMON_PROGRAMS
StartMenuFolder property | Full path to Start Menu Folder for All Users. Exists on Windows 2000 and Windows NT. | CSIDL_COMMON_STARTMENU
StartUpFolder property | Full path to Start Up Folder for All Users. Exists on Windows 2000 and Windows NT. | CSIDL_COMMON_STARTUP
TemplateFolder property | Full path to the Template Folder for All Users. Exists on Windows 2000. | CSIDL_COMMON_TEMPLATES
AdminToolsFolder property | Full path to the file system directory that stores administrative tools for All Users. Exists on Windows 2000. | CSIDL_COMMON_ADMINTOOLS
AppDataFolder property | Full path to the Application Data folder for the current user. Exists on Windows 2000, Windows NT, Microsoft Windows 98, and Microsoft Windows 95. | CSIDL_APPDATA
CommonAppDataFolder | Full path to the file directory containing application data for All Users. Exists on Windows 2000. | CSIDL_COMMON_APPDATA
FavoritesFolder property | Full path of the Favorites folder for the current user. Exists on Windows 2000, Windows NT, Windows 98, and Windows 95. | CSIDL_FAVORITES
PersonalFolder property | Full path to the Personal folder for the current user. Exists on Windows 2000, Windows NT, Windows 98, and Windows 95. | CSIDL_PERSONAL
SendToFolder property | Full path to the SendTo folder for the current user. Exists on Windows 2000, Windows NT, Windows 98, and Windows 95. | CSIDL_SENDTO
FontsFolder property | Full path to the system Fonts folder. Exists on Windows 2000, Windows NT, Windows 98, and Windows 95. | CSIDL_FONTS
ProgramFilesFolder property | Full path to the Program Files folder for the current user. Exists on Windows 2000, Windows NT, Windows 98, and Windows 95. | CSIDL_PROGRAM_FILES
ProgramFilesFolder | Full path to the Program Files folder for the current user. Exists on Windows NT and Windows 2000. | CSIDL_PROGRAM_FILESX86
CommonFilesFolder property | Full path to the Common Files folder for the current user. Exists on Windows 2000 and Windows NT. | CSIDL_PROGRAM_FILES_COMMON
CommonFilesFolder property | Full path to the Common Files folder for the current user. Exists on Windows NT and Windows 2000. | CSIDL_PROGRAM_FILES_COMMONX86
WindowsFolder property | Full path to the Windows folder for the current user. Exists on Windows 2000, Windows NT, Windows 98, and Windows 95. | CSIDL_WINDOWS
SystemFolder property | Full path to the System folder for the current user. Exists on Windows NT and Windows 2000. | CSIDL_SYSTEMX86
CommonAppDataFolder property | Full path to the file directory containing application data for all users. Exists on Windows 2000, Windows NT, Windows 98, and Windows 95. | CSIDL_COMMONAPPDATA
LocalAppDataFolder property | Full path to the file system directory that serves as the data repository for local (non-roaming) applications. Exists on Windows 2000, Windows NT, Windows 98, and Windows 95. | CSIDL_LOCAL_APPDATA
MyPicturesFolder property | Full path to the MyPictures folder. Exists on Windows 2000, Windows NT, Windows 98, and Windows 95. | CSIDL_MYPICTURES

Note The Alpha platform is not supported by Windows Installer version 1.1.

See Also

How do I specify a per-user or per-machine installation?, Per-User Installations


Per-User Installations

Per-user installation of an application means the application is available only for a particular user.

  • The application is installed only for a particular user.
  • Shortcuts are installed only to that users' profile.
  • Applications appear only on the Add/Remove Control Panel of users that have installed the applications.
  • On Microsoft® Windows® 2000, COM registration is written to HKCU\Software\Classes.
  • May or may not run at elevated privileges.
  • Icons and transforms are stored in %USERPROFILE%\Application Data\Microsoft\Installer\{ProductCode GUID}
  • The installer sets the following properties during a per-user installations.
Property | Description | CSIDL
DesktopFolder | Full path to the Desktop Folder for the current user. Exists on Windows 2000, Windows NT, Windows 98, and Windows 95. | CSIDL_DESKTOPDIRECTORY
ProgramMenuFolder | Full path to the Program Menu Folder for the current user. Exists on Windows 2000, Windows NT, Windows 98, and Windows 95. | CSIDL_PROGRAMS
StartMenuFolder | Full path to Start Menu Folder for the current user. Exists on Windows 2000, Windows NT, Windows 98, and Windows 95. | CSIDL_STARTMENU
StartUpFolder | Full path to Start Up Folder for the current user. Exists on Windows 2000, Windows NT, Windows 98, and Windows 95. | CSIDL_STARTUP
TemplateFolder | Full path to the Template Folder for the current user. Exists on Windows 2000, Windows NT, Windows 98, and Windows 95. | CSIDL_TEMPLATES
AdminToolsFolder | Full path to the file system directory that stores administrative tools for the current user. Exists on Windows 2000. | CSIDL_ADMINTOOLS
AppDataFolder | Full path to the Application Data folder for the current user. Exists on Windows 2000, Windows NT, Windows 98, and Windows 95. | CSIDL_APPDATA
CommonAppDataFolder | Full path to the file directory containing application data for all users. Exists on Windows 2000. | CSIDL_COMMON_APPDATA
FavoritesFolder | Full path of the Favorites folder for the current user. Exists on Windows 2000, Windows NT, Windows 98, and Windows 95. | CSIDL_FAVORITES
PersonalFolder | Full path to the Personal folder for the current user. Exists on Windows 2000, Windows NT, Windows 98, and Windows 95. | CSIDL_PERSONAL
SendToFolder | Full path to the SendTo folder for the current user. Exists on Windows 2000, Windows NT, Windows 98, and Windows 95. | CSIDL_SENDTO
FontsFolder | Full path to the system Fonts folder. Exists on Windows 2000, Windows NT, Windows 98, and Windows 95. | CSIDL_FONTS
ProgramFilesFolder | Full path to the Program Files folder for the current user. Exists on Windows 2000, Windows NT, Windows 98, and Windows 95. | CSIDL_PROGRAM_FILES
ProgramFilesFolder | Full path to the Program Files folder for the current user. Exists on Windows NT and Windows 2000. | CSIDL_PROGRAM_FILESX86
CommonFilesFolder property | Full path to the Common Files folder for the current user. Exists on Windows 2000 and Windows NT. | CSIDL_PROGRAM_FILES_COMMON
CommonFilesFolder property | Full path to the Common Files folder for the current user. Exists on Windows NT and Windows 2000. | CSIDL_PROGRAM_FILES_COMMONX86
WindowsFolder | Full path to the Windows folder for the current user. Exists on Windows 2000, Windows NT, Windows 98, and Windows 95. | CSIDL_WINDOWS
SystemFolder | Full path to the System folder for the current user. Exists on Windows NT and Windows 2000. | CSIDL_SYSTEMX86
CommonAppDataFolder | Full path to the file directory containing application data for all users. Exists on Windows 2000, Windows NT, Windows 98, and Windows 95. | CSIDL_COMMONAPPDATA
LocalAppDataFolder | Full path to the file system directory that serves as the data repository for local (non-roaming) applications. Exists on Windows 2000, Windows NT, Windows 98, and Windows 95. | CSIDL_LOCAL_APPDATA
MyPicturesFolder | Full path to the MyPictures folder. Exists on Windows 2000, Windows NT, Windows 98, and Windows 95. | CSIDL_MYPICTURES

Note The Alpha platform is not supported by Windows Installer version 1.1.

See Also

Per-Machine Installations, How do I specify a per-user or per-machine installation?


Using Windows Installer

This section describes how to use Microsoft® Windows® Installer to organize applications into components and download an application from an Internet location:

  • Organizing Applications into Components
  • Downloading an Installation From the Internet
  • Concurrent Installations
  • Using Cabinets and Compressed Sources
  • Using Qualified Components
  • Using Transitive Components
  • Localizing a Windows Installer Package
  • Code Page Handling (Windows Installer)
  • Localizing the Error and ActionText Tables
  • Searching for Existing Applications, Files, Registry Entries or .ini File Entries
  • Checking the Installation of Features, Components, Files
  • Installing Permanent Components, Files, Fonts, Registry Keys
  • Removing Stranded Files
  • Searching for a Broken Feature or Component
  • Replacing Existing Files
  • Editing Installer Shortcuts
  • Installing from Terminal Server
  • Using Isolated Components
  • How do I specify a per-user or per-machine installation?
  • How do I install a COM+ application with the Windows Installer?
  • How do I add or remove registry keys on the installation or removal of components?
  • How do I add and remove an application and leave no trace in the registry?
  • How do I install a package with elevated privileges as a non-admin?
  • How do I change the target location for a directory?


Organizing Applications into Components

The Microsoft® Windows® Installer installs and removes an application or product from a user's system in pieces referred to as components. Components are collections of resources that are always installed or removed from a user's system together. A resource can be a file, registry key, shortcut, or anything else that may be installed. Every component is assigned a unique component code GUID.

Authors of installation packages should only create components, and versions of components, that can be installed and removed without damaging other components. Also, the removal of a component should not leave behind orphan resources on the user's computer, such as unused files, registry keys, or shortcuts. To ensure this, authors should adhere to the following general rules whenever organizing resources into components:

  • Never create two components that install a resource under the same name and target location. If a resource must be duplicated in multiple components, change its name or target location in each component. This rule should be applied across applications, products, product versions, and companies.
  • Note that the previous rule means that no two components can ever have the same key path file. The key path value points to a particular file or folder belonging to the component which the installer uses to detect the component. If two components had the same key path file, the installer would be unable to distinguish which component is installed. Two components however may share a key path folder.
  • Never create a version of a component that is not compatible with all previous versions of the component. This rule should be applied across applications, products, product versions, and companies.
  • Don't create components that contain resources which will need to be installed into more than one directory on the user's system. The installer installs all the resources in a component into the same directory. It is not possible to install some resources into subdirectories.
  • Don't include more than one COM server per component. If a component contains a COM server, this must be the key path for the component.
  • Don't specify more than one file per component as a target for a Start menu or desktop shortcut.

When organizing an application into components, package authors may need to add, remove, or modify the resources in an existing installation. In this case, the author must decide whether to provide the resources by introducing a new component or by modifying existing components and changing them into a new versions of the component. Because a unique component code must be assigned when a new component is introduced, authors must determine whether their changes require changing the component code. For more information, see Changing the Component Code, What happens if the component rules are broken?, or Defining Installer Components.


Changing the Component Code

When specifying the components for an installation, package authors should follow the general rules for component organization described in Organizing Applications into Components. Authors may need to introduce new components or modify existing components. If the addition, removal, or modification of resources effectively creates a new component, then the component code must also be changed.

Creating a New Component

Introduce a new component and assign it a unique component code when making any of the following changes:

  • Any change that has not been shown by testing to be compatible with previous versions of the component. In this case, you must also change the name or target location of every resource in the component.
  • A change in the name or target location of any file, registry key, shortcut, or other resource in the component. In this case, you must also change the name or target location of every resource in the component.
  • Addition or removal of any file, registry key, shortcut, or other resource from the component. In this case, you must also change the name or target location every resource in the component.
  • Recompiling a 32-bit component into a 64-bit component.

When introducing a new component, authors need to do one of the following to ensure that the component does not conflict with any existing components:

  • Change the name or target location of any resource that may be installed under the same name and target location by another component.
  • Otherwise guarantee that the new component is never installed into the same folder as another component which has a resource under a common name and location. This includes localized versions of files with the same file name. For more information, see What happens if the component rules are broken?.
  • When changing the component code of an existing component, also change the name or target location of every file, registry key, shortcut, and other resource in the component.

Creating a New Version of a Component

A new version of a component is assigned the same component code as another existing component. Modifying a component without changing the component code is only optional in the following cases:

  • The changes to the component been proven by testing to be backward compatible with all previous versions of the component.
  • The author can guarantee that the new version of the component will never be installed on a system where it would conflict with previous versions of the component or applications requiring a previous version. For more information, see What happens if the component rules are broken?.

The component code of a new version of a component must not be changed when it would result in two components sharing resources, such as registry values, files, or shortcuts.


What happens if the component rules are broken?

In certain cases, authors may decide they need to break the rules for creating components as discussed in Organizing Applications into Components and Changing the Component Code. Authors need to be aware of the possible consequences of doing this and must otherwise guarantee that their components are never installed where they can damage other applications or components on the user's system.

The following describes ways that authors sometimes break the recommended component rules and the possible consequences.

An author adds resources to a component without the changing the component code.

  • Products installed with the old component have no information about the added resources in their installation database.
  • If both a new product that has the added resources and an old product are installed on the same computer, the resources can be left behind if the new product is uninstalled first.
  • An old product without the added resources cannot repair the newer version of the component. Reinstalling the old product does not restore the added resources.

An author removes resources from a component without changing the component code.

  • Products installed with the new component have no information about the removed resources in their installation database.
  • If both an old product, having the resource information, and a new product are installed on the same computer, the resources can be left behind if the old product is uninstalled first.
  • A new product with the removed resources cannot repair the older version of the product. Reinstalling the new product does not restore the removed resources.

An author includes a file that is incompatible with previous versions without changing the component code.

If an incompatible file is included in a component without changing the component code, default file versioning causes the installer to overwrite the original file with the more recent incompatible file. This can damage old products needing the original file. It may also prevent the installer from repairing the old product because the version of a component's key path file determines the version of the component. If a newer version of the key path file is already installed, the installer does not install the an older version of the component. For more information, see File Versioning Rules. In this case, the new product must be removed before the old product can be reinstalled.

  • Default file versioning causes the installer to overwrite the original file with the more recent incompatible file.
  • Old products that need the original file are damaged.
  • It may also prevent the installer from repairing the old product because the version of a component's key path file determines the version of the component. If a newer version of the key path file is already installed, the installer does not install the older version of the component. For more information, see File Versioning Rules. In this case, the new product must be removed before the old product can be reinstalled.

An author includes the same resource in two different components.

If two components have a resource under the same name and location and both components are installed into the same folder, then the removal of either component removes the common resource, which damages the remaining component.

  • Uninstalling either component removes the resource and breaks the other component.
  • The component reference-counting mechanism is damaged.


Defining Installer Components

The following outlines how to organize your application into Windows Installer components.

To organize an application into components

  1. Begin by obtaining a directory and file tree for all the files and other resources used in your application.
  2. Identify any files, registry keys, shortcuts, or other resources that are shared across applications and which can be provided by existing components available as merge modules. You must not include any of these resources in the components you author. Instead obtain these components by merging the merge modules into your installation package. The following steps describe how to organize the remaining resources of the application into components.
  3. Define a new component for every .exe, .dll, and .ocx file. Designate these files as the key path files of their components. Assign each component a component code GUID.
  4. Define a new component for every .hlp or .chm help file. Designate these files as the key path files of their components. Add the .cnt or .chi files to the components holding their associated .hlp and .chm files. Assign each component a component code GUID.
  5. Define a new component for every file that serves as a target of a shortcut. Designate these files as the key path files of their components. Assign each component a component code GUID.
  6. Group all the remaining resources into folders. All resources in each folder must ship together. If there is a possibility that a pair of resources may ship separately in the future, put these in separate folders. Define a new component for every folder. Try to keep the total number of components low to improve performance. Divide the application into many components when it is necessary to have the installer check the validity of the installation thoroughly. Designate any file in the component as the key path file. Assign each component a component code GUID.
  7. Add registry keys to the components. Any registry key that points to a file should be included in that file's component. Other registry keys should be logically grouped with the files that require them.


Downloading an Installation from the Internet

Microsoft® Windows® Installer accepts a Uniform Resource Locator (URL) as a valid source for an installation. If the installation database is at a URL, the installer downloads the database to a cache location before starting the installation. The installer also downloads the files and cabinet files from the internet source that are appropriate for the user's selections.

For example, to install a package with a source located on a Web server at http://server/share/package.msi, you can use the command line options to install the package and set public properties.

msiexec /i http://server/share/package.msi PROPERTY=VALUE

Note that for Windows Installer version 1.0 the .msi file and any external source files must located together at the source root. It is not valid to store cabinet files and the .msi file in separate locations.

A command line like the one previously shown should be passed to the installer to start an installation from a Web browser. In general, you should not download and install the package simply by double-clicking on the .msi file from within the browser. This downloads the .msi file to the temporary Internet files folder and would pass the following command to the installer.

msiexec /i c:\windows\temporary internet files\package.msi

The installation fails if the package requires any external source files or cabinets because these are not located in the same location as the .msi file.

The InstallProduct method could be used to run the above command from a browser as an on-click event.

<SCRIPT LANGUAGE="VBScript">
<!--
Dim Installer
On Error Resume Next
set Installer=CreateObject("WindowsInstaller.Installer")
Installer.InstallProduct "http://server/share/package.msi", "PROPERTY=VALUE "
set Installer=Nothing
-->
</SCRIPT>

Note that because some Web servers are case sensitive, the FileName field in the File table must match the case of the source files exactly to ensure support of Internet downloads.

See also Downloading and Installing a Patch From the Internet.


Concurrent Installations

The Windows Installer can only run one installation at a time unless it is a nested installation. A nested installation action installs another Windows Installer package during a currently running installation and is considered a single application. Nested installations are not available with Windows Installer version 1.0. For more information see Nested Installation Actions.

Two installations cannot be run in the same process, an attempt to call the installer's application programming interface (API) returns ERROR_INSTALL_ALREADY_RUNNING in two cases:

  • While the _MSIExecute mutex is set. The _MSIExecute mutex is set only while processing the InstallExecuteSequence table, the AdminExecuteSequence table, or the AdvtExecuteSequence table.
  • While the current process is processing the InstallUISequence table or AdminUISequence table.


Using Cabinets and Compressed Sources

This section discusses compressed and uncompressed sources and adding cabinet files to an installation:

  • Compressed and Uncompressed Sources
  • Cabinet Files
  • Including a Cabinet File in an Installation


Compressed and Uncompressed Sources

Package authors can reduce the size of their installation packages by compressing the source files and including them in cabinet files. The source file image can be compressed, uncompressed, or a mixture of both types.

Compressed Sources

A source consisting entirely of compressed files should include the compressed flag bit in the Word Count Summary Property. The compressed source files must be stored in cabinet files located in a data stream inside the .msi file or in a separate cabinet file located at the root of the source tree. All the cabinets in the source must be listed in the Media table.

Uncompressed Sources

A source consisting entirely of uncompressed source files should omit the compressed flag bit from the Word Count Summary Property. All the uncompressed files in the source must exist in the source tree specified by the Directory Table.

Mixed Sources

To mix compressed and uncompressed source files in the same package, override the Word Count Summary property default by setting the msidbFileAttributesCompressed or msidbFileAttributesNoncompressed bit flags on particular files. These bit flags are set in the Attributes column of the File table if the compression state of the file does not match the default specified by the Word Count Summary property.

For example, if the Word Count Summary property has the compressed flag bit set, all files are treated as compressed into a cabinet. Any uncompressed files in the source must include msidbFileAttributesNoncompressed in the Attributes column of the File table. The uncompressed files must be located at the root of the source tree.

If the Word Count Summary property has the uncompressed flag set, files are treated as uncompressed by default and any compressed files must include msidbFileAttributesCompressed in the Attributes column of the File table. All the compressed files must be stored in cabinet files located in a data stream inside the .msi file or in a separate cabinet file located at the root of the source tree.

For more information, see Including a Cabinet File in an Installation and Cabinet Files.


Cabinet Files

A cabinet is a single file, usually with a .cab extension, that stores compressed files in a file library. The cabinet format is an efficient way to package multiple files because compression is performed across file boundaries, which significantly improves the compression ratio.

Developers can use a cabinet file creation tool such as Makecab.exe to make cabinet files for use with installer packages.

Developers can also use a cabinet file creation tool such as Cabarc.exe to make cabinet files for use with installer packages. This tool writes to the Diamond cabinet structure.

The file keys of the files stored inside of a cabinet file must match the entries in the File column of the File table and the sequence of files in the cabinet must match the file sequence specified in the Sequence column. For more information, see Including a Cabinet File in an Installation.

Large files can be split between two or more cabinet files. There can be no more than 15 files in any one cabinet file that spans to the next cabinet file. For example, if you have three cabinet files the first cabinet can have 15 files that span to the second cabinet file and the second cabinet file can have 15 files that span to the third cabinet file.

A cabinet file can be located inside or outside of the .msi file. To conserve disk space, the installer always removes any cabinets that are embedded in the .msi file before caching the installation package on the user's computer.

The installer extracts files from a cabinet as the they are needed by the installation and installs them in the same order they are stored in the cabinet file. The space requirements for installing a file stored in a cabinet are no different than for installing an uncompressed file.


Including a Cabinet File in an Installation

This section describes including cabinet files in installations.

To include a cabinet file in a installation package

  1. Use a cabinet creation tool to compress the source files into a cabinet file. See Cabinet Files.
  2. The cabinet file must either be located in a data stream inside the .msi file or in a separate cabinet file located at the root of the source tree specified by the Directory Table.
  3. Determine whether the source is to be a compressed type or a mixed type that has both uncompressed and compressed files. See Compressed and Uncompressed Sources. Depending on the type of source image, set the compressed or uncompressed flag bits of the Word Count Summary Property.
  4. Add a record to the File table for each of the files in the cabinet. Enter a file key in the File column that exactly matches the file key of the file in the cabinet. The file keys are case-sensitive. The file installation sequence in the File table and the cabinet must also be the same. The file sequence is specified by the sequence number in the Sequence column. To arrive at the sequence number for the first file in the cabinet, do the following. Find the existing record in the Media table having the greatest value in the DiskID column. The LastSequence field of this record gives the last file sequence number used on the media. In the File table, assign the first file of the new cabinet a sequence number that is greater than this. Assign sequence numbers to all the remaining files in the same order as in the cabinet file. For a description of the remaining record fields, see File table.
  5. Add a record to the Media table for the cabinet. Specify a value in the DiskId field of this new record that is greater than the largest DiskId value already existing in the table. Put the name of the cabinet into the Cabinet field. This name must be in the form of a Cabinet data type. Prefix the name with a number sign "#" if the cabinet is a data stream stored in the .msi file. Note that if the cabinet is a data stream, the name of the cabinet is case-sensitive. If the cabinet is a separate file, the name of the file is not case-sensitive.
  6. Determine the greatest file sequence number in the new cabinet by checking the Sequence column of the updated File table. Enter a value that is greater than this into the LastSequence field of the new record of the Media table. For a description of the remaining record fields, see Media table.
  7. You can store the cabinet file in the installation package either by using a tool such as Msidb.exe or by using the installer's Database Functions. The following four steps explain how to add the cabinet from a program by using the database functions.
  8. To add the cabinet to the installation package from a program open a view on the _Streams table of the database using MsiDatabaseOpenView.
  9. Use MsiRecordSetString to set the Name column of the _Streams table to the name appearing in the Cabinet column of the Media table. Omit the number sign #.
  10. Use MsiRecordSetStream to set the Data column of the of the _Streams table to the cabinet's data.
  11. Use MsiViewModify to update the record in the _Streams table.
  12. To use Msidb.exe to add the cabinet file Mycab.cab to the installation package named Mydatabase.msi, use the following command line: Msidb.exe -d mydatabase.msi -a mycab.cab. In this case, the Cabinet column of the Media table should contain the string: #mycab.cab.


Using Qualified Components

Qualified components are a method of indirection and can be used to group components with parallel functionality into categories.

To return the full path and install a qualified component, call MsiProvideQualifiedComponent or MsiProvideQualifiedComponentEx.

To enumerate all the qualified component qualifiers and descriptive strings, call MsiEnumComponentQualifiers.

To group components together into a qualified-component category

  1. There must be a record in the Component table for each component that is included in the new category of qualified components. Author the fields in the Component table the same as for ordinary components. Note that each qualified component must have a unique component ID GUID entered in the ComponentId column of the Component table.
  2. Generate a qualifier text string for each qualified component. The qualifier must be unique text string that can be easily generated when searching for a qualified component. For example, if the components in the category are being qualified by language, the numeric locale identifier (LCID) is a reasonable qualifier string.
  3. Add a record in the PublishComponent table for each qualified component. Enter the qualified-component identifiers from the Component column of the Component table into the Component_ column of the PublishComponent table. Enter the qualifier strings for each qualified component into the Qualifier column. Enter a localized string to be displayed to the user and describing the qualified component into the optional AppData column. An explanatory string should be put in the AppData field, such as "French Dictionary," rather than just the numeric LCID. Enter the name of the feature that uses this component into the Feature_ column. The feature identifier in this field must also be listed in the Feature column of the Feature table.
  4. Generate a category GUID for this category of qualified components. This must be a valid GUID. If you use a utility such as GUIDGEN to generate the GUID be sure that it contains only uppercase letters. For every qualified component in this category, enter the category GUID into the ComponentId field of the PublishComponent table.

The following example illustrates how the "FAX Templates" category of qualified components are authored into the Component, Feature, and PublishComponent tables.

PublishComponent Table

ComponentId | Qualifier | AppData | Feature_ | Component_
{FAX Template Category GUID} | 1033 | US English template | FAXTemplate | FAXTemplateENU
 | 1041 | Japanese template | FAXTemplate | FAXTemplateJPN
 | 1054 | Thai template | FAXTemplate | FAXTemplateTHA
 | 1031 | German template | FAXTemplate | FAXTemplateDEU

Component Table (partial table)

Component | ComponentId
FAXTemplateENU | {FAX Template (US English) component GUID}
FAXTemplateJPN | {FAX Template (Japanese) component GUID}
FAXTemplateTHA | {FAX Template (Thai) component GUID}
FAXTemplateDEU | {FAX Template (German) component GUID}

Feature Table (partial table)

Feature
FAXTemplate
FAXTemplate
FAXTemplate
FAXTemplate


Using Transitive Components

A typical use for transitive components is to prepare a product to gracefully reinstall during an upgrade from Microsoft® Windows® 98 to Microsoft Windows® 2000. This is an aspect of Resiliency. The author of the installation package specifies those components that need to be swapped out during a system upgrade as having the transitive attribute. When the user later upgrades the system from Windows 98 to Windows 2000, the product has to be reinstalled. Upon this reinstall, the installer removes the Windows 98 components and installs the Windows 2000 components, saving having to install the entire product.

To include two transitive components in the installation package

  1. Include both transitive components in the installation package.
  2. Author both transitive components into the Component table the same as regular components. Each transitive component must have its own unique GUID specified in the ComponentId column.
  3. Include the msidbComponentAttributesTransitive bit in the Attributes column of the Component table for each transitive component. If this bit is set, the installer reevaluates the value of the statement in the Condition column upon a reinstall. If the value was previously False and has changed to True, the installer installs the component. If the value was previously True and has changed to False the installer removes the component even if the component has other products as clients. Note that unless the transitive bit is set, the component remains enabled once installed even if the conditional statement evaluates to False on a subsequent maintenance installation of the product. Note that the conditions must be based only on machine states. Do not use with conditions based on user states or properties set on the command line because this can cause the installer to require a reinstall of the product on each use by a different user.
  4. Enter complementary conditional expressions into the Condition fields of the Control table such that whenever the condition on the first transitive component changes to False the condition on the second transitive component changes to True. This results in the removal of the first component and installation of the second component upon reinstallation of the application.

A reinstallation of the product is necessary to switch the transitive components. Package authors therefore need to provide users with a method for reinstalling the product and for setting the modes of the REINSTALLMODE property. There are basically three ways to trigger the reinstallation.

  • Run and configure the reinstallation through the user interface by authoring a package that uses the full UI.
  • Run the reinstallation from the command line by using msiexec /f and select the modes from the list for the /f command line option.
  • Have the application can call MsiReInstallProduct or MsiReInstallFeature.

The bit should only be used with conditions based on machine states. Do not use with conditions based on user states or properties set on the command line because this can cause the installer to require a reinstall of the product on each use by a different user.

Note that unless the Transitive bit in the Attributes column is set for a component, the component remains enabled once installed even if the conditional statement in the Condition column evaluates to False on a subsequent maintenance installation of the product.


Localizing a Windows Installer Package

For general information about localization, see National Language Support in the Platform SDK documentation. Localizing a Microsoft® Windows® Installer package requires modifying the strings displayed by the user interface and may also require adding or modifying product resources. For example, localization may include the addition of international DLLs and localized files to the product.

To localize a Windows Installer package

  1. Prepare for localization when authoring the original installation package. Design the layout of localized files such that different language versions can safely coexist when installed on the user's computer. Organize files requiring localization into separate components and install these files into separate directories. Author a base installation database that has a neutral control page. See Preparing a Windows Installer package for localization.
  2. Always set the code page of the database being localized prior to adding any localized data. If the code page of the database being localized is neutral, see Setting the code page of a database. To determine the code page see Determining an installation database's code page.
  3. Import a localized Error table and ActionText table into the database. For more information, see Localizing the Error and ActionText Tables for a list of languages supported by the Platform SDK. You may import these tables using Msidb.exe or MsiDatabaseImport.
  4. Modify any of the other localizable columns in the database using a table editor or SQL queries. For the SQL access functions, see Working With Queries. The topics for the database tables identify which database columns can be localized. For more information, see the list of tables in Database Tables.
  5. Set the ProductLanguage property in the Property table to the LANGID of the database.
  6. Set the language field of the Template Summary Property to reflect the LANGID of the database.
  7. If the text strings in the summary information stream are localized, set the Codepage Summary Property to the code page.
  8. Set the ProductCode property in the Property table and set the package code in the Revision Number Summary Property to a new package code. A localized product is considered a different product. For example, the German and English versions of an application are considered two different products and must have different product codes.
  9. Localization may require modifying resources that already exist or the addition of new resources such as files or registry keys. Check to be sure that the component code is changed for every existing component that has had a new resource added. Other modifications may also require changes to a component's code. For more information see Changing the Component Code.
  10. Be sure to save localization and other changes to the database by saving the package with the editing tool or by calling MsiDatabaseCommit.

For more information, see A Localization Example.


Code Page Handling (Windows Installer)

The Windows Installer stores all database strings in a single shared string pool to reduce the size of the database and to improve performance. The database has a single ANSI code page for the string pool appropriate for the product's localization. For list of numeric code pages, see Localizing the Error and ActionText Tables. See also Determining an installation database's code page.

Localizing a Windows installer package may involve modifying information in database tables, exporting these tables to ANSI text archive files, and then importing the archive files into the database being localized. Authors may also add localization changes to a database using a database table editor or the Database Functions. It is important to set the code page of the database being localized prior to making any localization changes to the database. Attempting to set the code page of the database after localizing the database is not recommended because this can corrupt extended characters. For details, see Setting the code page of a database.

The recommended approach for handling code pages is to author a neutral database that only contains characters that can be translated into any code page. For more information, see Creating a database with a neutral code page.

Authors adding localization information with database archive files may use MsiDatabaseExport to export tables from a database containing localization changes to ANSI text archive files and then import these into the database being localized with MsiDatabaseImport. The code page of an exported archive file is always the same as its parent database. The code pages of an imported file and the database receiving the file must be identical, or at least one of the two code pages must be neutral. See Code Page Handling of Imported and Exported Tables.

Authors adding localization information with a text editor or the Database Functions must be careful to only pass string parameters to the Windows Installer API that use the code page of the database being localized. If a string parameter contains characters not represented by the code page of the database is passed, an error occurs when calling MsiDatabaseCommit. See Code Page Handling of Parameter Strings.

In cases where one package is used for the installation of multiple language versions of a product, the transform used to localize strings can also change the code page of the database.


Code Page Handling of Imported and Exported Tables

Authors may add localization information to an installation database by importing and exporting ASCII text archive files using MsiDatabaseExport and MsiDatabaseImport. Because the database string pool uses an ANSI code page, both the database and exported text archive files have code pages. When a text archive file is exported from a database, the code page of the archive file is the same as the parent database. See Localizing the Error and ActionText Tables for a list of numeric code pages.

The ASCII text archive files exported by MsiDatabaseExport have the following format. Note that exporting a table to a text archive file translates the control characters to avoid conflicts with file delimiters. The names of the table columns are written on the first line. The column formats are written on the second line. If the table contains only ASCII data, the third line of the text file is the table's name followed by a list of the primary keys. If the table contains non-ASCII data and the database is stamped with a numeric code page, the code page number appears at the beginning of the third line. If the database contains non-ASCII data but the database is not stamped with the numeric code page, the current system's code page number is written at the beginning of the third line. The remaining lines of the text file are the data in the specified code page. If a table contains streams, MsiDatabaseExport exports each stream in the table to a separate file.

Localization is greatly facilitated by starting with a database having a neutral code page. A blank database has a neutral code page. A database containing no extended characters that require a code page to be represented in ASCII has a neutral code page. See Creating a database with a neutral code page. If a text archive file with a non-neutral code page is imported into a database that has a different non-neutral code page, the installer returns an error when calling MsiDatabaseImport. A text archive file that has a neutral code page can be imported into a database having any code page. A text archive file having any code page can be imported into a database having a neutral code page. Importing a text archive file into a database with a neutral code page sets the code page of the database to the archive file's code page. All archive files subsequently imported into the database must then have the same code page as the first file. See Determining an installation database's code page and Setting the code page of a database.

The text archive files exported by MsiDatabaseExport are intended for use with version control systems, use the Database Functions or a database table editor for editing the database.

Authors may also add localization information to an installation database using a database table editor or the Windows Installer API. See Code Page Handling of Parameter Strings.


Code Page Handling of Parameter Strings

Authors may add localization information to an installation database by using a database table editor such as Orca, provided with the Windows Installer SDK, or by calling the Database Functions from a program. Authors must be careful to only pass string parameters that use the code page of the database that is being localized. If a string parameter contains characters that cannot be represented by the code page of the database, the installer returns an error when calling MsiDatabaseImport. See Determining an installation database's code page and a list of numeric code pages see Localizing the Error and ActionText Tables.

Windows 98 and Windows 95

When adding localization information to a database using Windows 95 or Windows 98, the code page of the database must be neutral or it must match the current code page of the system. In this case, the strings passed to the Database Functions must be code-page neutral or require the same code page as the database.

Windows NT and Windows 2000

When adding localization information to a database using Windows NT or Windows 2000, the code page of the database must be supported by the system. It does not have to be the current code page of the system. IsValidCodePage must return TRUE for the database's code page. Note that because Windows NT and Windows 2000 convert ANSI strings to Unicode, there is an error if the current user's code page is not the same as the database's code page.

Calling the ANSI version of the Windows Installer API on Windows NT or Windows 2000 converts the localized string to Unicode using the current system code page. When the database is committed, the Unicode string is converted to ANSI using the code page of the database. This can result in a loss of data and incorrect string conversion if the current system's code page differs from the code page of the localized string. The following procedure will ensure that the localization data is properly stored.

  1. Set the code page of the database to the code page of the localized string.
  2. Convert the ANSI string to Unicode using the Win32 function MultiByteToWideChar and specify the code page of the localized data.
  3. Call the Unicode version of the Windows Installer API with the Unicode string to add the localized data.
  4. Commit the localization changes to the database with MsiDatabaseCommit.

Authors may also add localization information to an installation database by importing and exporting ASCII text archive files. For more information, see Code Page Handling of Imported and Exported Tables.


Creating a Database with a Neutral Code Page

The recommended approach for handling code pages is to author a neutral base database that only contains characters that can be translated into any code page. The database may then be set to the code page of the localization and the localization information can be added as described in Localizing a Windows Installer Package.

To author a neutral database, avoid extended characters that do not belong to the ASCII character set and therefore require a special code page. For example, the copyright sign, ©, and the registered trademark sign, ®, are not ASCII characters, and require a special ANSI code page for proper display. Instead use (c) and (r), because these characters can be translated or transformed to the symbols for the English-language version. This neutral database can then be localized by setting its code page and then adding localization information by table editing or by importing text archive files.


Localizing the Error and ActionText Tables

The Platform SDK includes localized resource strings, localized Error tables, and localized ActionText tables for the languages listed in the following table. The LANGIDs marked with asterisks indicate that the resource strings are stored as the base language and so can be used with all dialects of that language.

You can import the localized Error and ActionText tables into your database by using Msidb.exe or MsiDatabaseImport.

LANGID (decimal) | LANGID (hexadecimal) | ASCII code page | Abbreviation | Language
1025* | 0x401 | 1256 | ARA | Arabic (Saudi Arabia)
1027 | 0x403 | 1252 | CAT | Catalan (Spain)
1028* | 0x404 | 950 | CHT | Chinese (Taiwan)
2052 | 0x804 | 936 | CHS | Chinese (People's Republic of China)
1029 | 0x405 | 1250 | CSY | Czech (Czech Republic)
1030 | 0x406 | 1252 | DAN | Danish (Denmark)
1031* | 0x407 | 1252 | DEU | German (Germany)
1032 | 0x408 | 1253 | ELL | Greek (Greece)
1033* | 0x409 | 1252 | ENU | English (United States)
3082* | 0xC0A | 1252 | ESN | Spanish - Modern Sort (Spain)
1035 | 0x40B | 1252 | FIN | Finnish (Finland)
1036* | 0x40C | 1252 | FRA | French (France)
1037 | 0x40D | 1255 | HEB | Hebrew (Israel)
1038 | 0x40E | 1250 | HUN | Hungarian (Hungary)
1040* | 0x410 | 1252 | ITA | Italian (Italy)
1041 | 0x411 | 932 | JPN | Japanese (Japan)
1042 | 0x412 | 949 | KOR | Korean (Korea)
1043* | 0x413 | 1252 | NLD | Dutch (Netherlands)
1044* | 0x414 | 1252 | NOR | Norwegian (Bokmål) (Norway)
1045 | 0x415 | 1250 | PLK | Polish (Poland)
1046 | 0x416 | 1252 | PTB | Portuguese (Brazil)
2070 | 0x816 | 1252 | PTG | Portuguese (Portugal)
1048 | 0x418 | 1250 | ROM | Romanian (Romania)
1049 | 0x419 | 1251 | RUS | Russian (Russia)
1050 | 0x41A | 1250 | HRV | Croatian (Croatia)
1051 | 0x41B | 1250 | SKY | Slovak (Slovakia)
1053* | 0x41D | 1252 | SVE | Swedish (Sweden)
1054 | 0x41E | 874 | THA | Thai (Thailand)
1055 | 0x41F | 1254 | TRK | Turkish (Turkey)
1060 | 0x424 | 1250 | SLV | Slovenian (Slovenia)
1066 | 0x42A | 1258 | VIT | Vietnamese (Viet Nam)
1069 | 0x42D | 1252 | EUQ | Basque (Spain)


Determining an Installation Database's Code Page

To determine the code page of a database, call MsiDatabaseExport with hDatabase set to the handle of the database and szTableName set to _ForceCodepage. This exports a text file with an .idt extension. The first two lines of this file are blank. The third line is the ANSI code page number, followed by a tab, followed by the name _ForceCodepage. See also Code Page Handling of Imported and Exported Tables.

An example of determining the code page by using the Export method is provided in the Windows Installer SDK as a part of the utility WiLangId.vbs. The following snippet, GetCP.vbs, also illustrates the Export method and is for use with Windows Scripting Host.

' GetCP.vbs . Argument(0) is the path to the database.Windows Installer utility to report the code page for a package

Option Explicit

' Connect to Windows Installer object
On Error Resume Next
Dim installer : Set installer = Nothing
Set installer = Wscript.CreateObject("WindowsInstaller.Installer")

' Open database
Dim databasePath:databasePath = Wscript.Arguments(0)
Dim database : Set database = installer.OpenDatabase(databasePath, 0)

' Extract compose report message
Dim message:message = "Database codepage = "         & DatabaseCodepage(database)
Set database = nothing
Wscript.Echo message
Wscript.Quit 0

' Get ANSI codepage of database text data
Function DatabaseCodepage(database)
    On Error Resume Next
    Dim WshShell : Set WshShell = Wscript.CreateObject("Wscript.Shell")
    Dim tempPath:tempPath = WshShell.ExpandEnvironmentStrings("%TEMP%")
    database.Export "_ForceCodepage", tempPath, "codepage.idt"
    Dim fileSys:Set fileSys = CreateObject("Scripting.FileSystemObject")
    Dim file:Set file = fileSys.OpenTextFile(tempPath & "\codepage.idt",
                        1, False, 0)
    file.ReadLine ' skip column name record
    file.ReadLine ' skip column defn record
    DatabaseCodepage = file.ReadLine
    Dim iDelim:iDelim = InStr(1, DatabaseCodepage, vbTab, vbTextCompare)
    If iDelim = 0 Then Fail "Failure in codepage export file"
    DatabaseCodepage = Left(DatabaseCodepage, iDelim - 1)
End Function

Use the following command line to get the code page of a database named MNPFren.msi.

Cscript GetCP.vbs MNPFren.msi


Localizing the Language Displayed by Dialogs

The Windows Installer service uses the current user's language in all dialogs until a Windows Installer package is opened. On Windows 2000 and later operating systems, the Windows Installer determines this by using GetUserDefaultUILanguage. On operating systems earlier than Windows 2000, it uses GetUserDefaultLangID. When a Windows Installer package is opened, the installer displays dialogs using the package's language as specified by the Template Summary Property.

For more information about localizing the language of a Windows Installer package, see also A Localization Example.


Setting the Code Page of a Database

Always set the code page of a database prior to adding any localization information. Attempting to set the code page after entering data into the database is not recommended because this could corrupt extended characters. Localization can be greatly facilitated by starting with a database that is code page neutral. For details, see Creating a database with a neutral code page. You may determine the current code page of a database as described in Determining an installation database's code page. See Localizing the Error and ActionText Tables for a list of numeric code pages.

You may set the code page of a blank database, or a database with a neutral code page, by importing a text archive file having a non-neutral code page with MsiDatabaseImport. This sets the code page of the database to the imported file's code page. All archive files subsequently imported into the database must then have the same code page as the first file. If a text archive file is exported from a database, the code page of the archive file is the same as the parent database. See Code Page Handling of Imported and Exported Tables.

The code page of any database may be set to a specified numeric code page by using MsiDatabaseImport to import a text archive file with the following format: Two blank lines; followed by a line containing the numeric code page, a tab delimiter, and the exact string: _ForceCodepage. Note that with Windows NT or Windows 2000, this translates all the strings in the database to the code page of _ForceCodepage. This may be intended when localizing an existing database and translating all non-neutral strings to the new code page. However, this causes an error if the database contains non-neutral strings that are not to be translated.

An example of setting the code page by using the Import method is provided in the Windows Installer SDK as a part of the utility WiLangId.vbs. The following snippet, SetCP.vbs, also illustrates the Import method and is for use with Windows Scripting Host.

' SetCP.vbs Argument(0) is the path to the package and Argument(1)
' is the new code page. Note that this must be one of the valid ANSI
' code page values for the system.

Option Explicit
' Connect to Windows Installer object
On Error Resume Next
Dim installer : Set installer = Nothing
Set installer = Wscript.CreateObject("WindowsInstaller.Installer")

' Open database
Dim databasePath:databasePath = Wscript.Arguments(0)
Dim database : Set database = installer.OpenDatabase(databasePath, 1)
' Update value
Dim value:value = Wscript.Arguments(1)
SetDatabaseCodepage database, value

' Extract language info and compose report message
Dim message: message = "Database codepage = "        & DatabaseCodepage(database)
database.Commit
Set database = nothing
Wscript.Echo message
Wscript.Quit 0

' Get ANSI codepage of database text data
Function DatabaseCodepage(database)
    On Error Resume Next
    Dim WshShell : Set WshShell = Wscript.CreateObject("Wscript.Shell")
    Dim tempPath:tempPath = WshShell.ExpandEnvironmentStrings("%TEMP%")
    database.Export "_ForceCodepage", tempPath, "codepage.idt"
    Dim fileSys : Set fileSys = CreateObject("Scripting.FileSystemObject")
    Dim file : Set file = fileSys.OpenTextFile(tempPath & "\codepage.idt", 1, False, 0)
    file.ReadLine ' skip column name record
    file.ReadLine ' skip column defn record
    DatabaseCodepage = file.ReadLine
    Dim iDelim:iDelim = InStr(1, DatabaseCodepage, vbTab, vbTextCompare)
    If iDelim = 0 Then Fail "Failure in codepage export file"
    DatabaseCodepage = Left(DatabaseCodepage, iDelim - 1)
End Function

' Set ANSI codepage of database text data
Sub SetDatabaseCodepage(database, codepage)
    On Error Resume Next
    If Not IsNumeric(codepage) Then Fail "Codepage must be numeric"
    Dim WshShell : Set WshShell = Wscript.CreateObject("Wscript.Shell")
    Dim tempPath:tempPath = WshShell.ExpandEnvironmentStrings("%TEMP%")
    Dim fileSys: Set fileSys= CreateObject("Scripting.FileSystemObject")
    Dim file: Set file= fileSys.OpenTextFile(tempPath & "\codepage.idt",
                        2, True, 0)
    file.WriteLine ' dummy column name record
    file.WriteLine ' dummy column defn record
    file.WriteLine codepage & vbTab & "_ForceCodepage"
    file.Close
    database.Import tempPath, "codepage.idt"
End Sub

Use the following command line to Set the code page of a database named MNPFren.msi to 1252.

Cscript SetCP.vbs MNPFren.msi 1252


Preparing a Windows Installer Package for Localization

Localization of a Windows Installer package into multiple languages can be greatly facilitated by doing the following:

  • Author a base installation database that is code page neutral. See Creating a database with a neutral code page. The code page of the localized database can then be set by importing a text archive table with a non-neutral code page into the base database. See Setting the code page of a database.
  • Organize files requiring localization into separate components and install these files into separate directories. This ensures that two localized packages never install identically named files into the same directory.

For example, a worldwide application using the following resources may have three components.

Component | Resource
WORLD | worldwide.exe
WORLD | worldwide registry entries
WORLD | worldwide shortcut
ENG | engui.dll
ENG | readme.txt
FRA | fraui.dll
FRA | readme.txt

The files that need to be localized may be installed into the following directories.

Location
[ProgramFilesFolder]\World\worldwide.exe
[ProgramFilesFolder]\World\English\engui.dll
[ProgramFilesFolder]\World\English\readme.txt
[ProgramFilesFolder]\World\French\fraui.dll
[ProgramFilesFolder]\World\French\readme.txt


Searching for Existing Applications, Files, Registry Entries or .ini File Entries

The Microsoft® Windows® Installer can search for a particular file or directory during an installation. File or directory searches are used to determine whether the user has already installed a version of an application.

The AppSearch Action searches the user's system for file signatures specified in the AppSearch table. If the AppSearch action finds an installed file or directory with the specified signature, it sets a corresponding property, also specified in the AppSearch table, to the location of the file or directory. When searching for a file, the file signature must also be listed in the Signature table. If a file signature is listed in the AppSearch table and is not listed in the Signature table, the search looks for a directory, registry entry, or .ini file entry.

To expedite the search of the user's computer, the installer queries the following locator database tables in the order listed for a suggested search location.

If the file signature is listed in the CompLocator table, the suggested search location is the key path of a component. If the signature is not listed in this table or not installed at the suggested location, the installer queries the RegLocator table for a suggested location.

If the file signature is listed in the RegLocator table, the suggested search location is a key path written in the user's registry. If the signature is not listed in this table or not installed at the suggested location, the installer queries the IniLocator table for a suggested location.

If the file signature is listed in the IniLocator table, the suggested search location is a key path written in an .ini file present in the default Windows directory of the user's system. If the signature is not listed in this table or not installed at the suggested location, the installer queries the DrLocator table for a suggested location.

If the file signature is listed in the DrLocator table, the suggested search location is a path in the user's directory tree. The depth of subdirectory levels to search below this location is also specified in this table.

The first time the installer finds the file signature at a suggested location, it stops searching for this file or directory and sets the corresponding property in the AppSearch table.

For more information about searching for files and directories, see:

How do I search all fixed drives for a file?

How do I search for a file in a specific location?

How do I search for a directory and a file in that directory?

How do I search for a file and create a property holding the file's path?

How do I search for a registry entry and create a property holding the value of the Registry?


How do I search all fixed drives for a file?

To search all fixed drives for a file

  1. Enter the file's signature and name in the Signature table. The remaining fields in this record can be null to search for any version of MyApp.exe.

    Signature Table (partial)
    Signature | Filename
    AppFile | MyApp.exe

  2. Enter the property that the installer is to set if MyApp.exe is installed.

    AppSearch Table
    Property | Signature
    MYAPP | AppFile

  3. Use the DrLocator table. Leave the Parent and Path fields empty to search all fixed drives of the user's system. Specify in the Depth column the number of subdirectory levels to search. For example, setting Depth to 0 would find c:\MyApp.exe but would not detect the file at a depth of 2, such as c:\Program Files\MyApps\MyApp.exe.

    DrLocator Table
    Signature | Parent | Path | Depth
    AppFile | 3

  4. Include the AppSearch action in the action sequence. If MyApp.exe is found to be installed, the installer sets the property MYAPP to the location of file. If the file is installed, MYAPP evaluates as True in a conditional expression.


How do I search for a file in a specific location?

To search for a file in a specific location on the user's system

  1. List the file's signature and name in the Signature table. The remaining fields in this record can be null to search for any version of MyApp.exe.

    Signature Table
    Signature | Filename
    AppFile | MyApp.exe

  2. Enter the property that the installer is to set if MyApp.exe is installed.

    AppSearch Table (partial)
    Property | Signature
    MYAPP | AppFile

  3. Use the DrLocator table. Enter the full path to the file on the user's system in the Path field. Enter a value of 0 into the Depth column to search the bin folder.

    DrLocator Table
    Signature | Parent | Path | Depth
    AppFile | c:\Program Files\MyProducts\Projects\bin | 0

  4. Include the AppSearch action in the action sequence. If MyApp.exe is installed in c:\Program Files\MyProducts\Projects\bin, the installer sets the property MYAPP to the location of file.


How do I search for a directory and a file in that directory?

To search for a directory and then a file in that directory

  1. First do a search for the directory. No record is included in the Signature table for the directory search. For the file search, list the file's signature and name in the Signature table. The remaining fields in this record can be null to search for any version of MyApp.exe.

    Signature Table (partial)
    Signature | Filename
    AppFile | MyApp.exe

  2. Enter the property that the installer is to set if the directory with the signature AppDir is installed. If the installer finds this directory is installed, it sets MYDIR to the directory's path. Enter the property that the installer is to set if MyApp.exe is installed.

    AppSearch Table (partial)
    Property | Signature
    MYDIR | AppDir
    MYAPP | AppFile

  3. Use the DrLocator table. Enter the property set to the directory path into the Parent column. Specify in the Depth column the number of subdirectory levels to search in this directory.

    DrLocator Table
    Signature | Parent | Path | Depth
    AppFile | MYDIR | 0

  4. Include the AppSearch action in the action sequence. If MyApp.exe is found to be installed in AppDir, the installer sets the property MYAPP to the location of file.


How do I search for a file and create a property holding the file's path?

To search for a file and create a property holding the path of that file

  1. First do a search for the file by listing the file's signature and name in the Signature table. The remaining fields of this record can be left empty to specify a search for any version of MyApp.exe.

    Signature Table (partial)
    Signature | Filename
    AppFile | MyApp.exe

  2. Next, specify the path of the file in being searched for in the DrLocator table. Because AppFolder is not listed in the Signature table, the installer determines that AppFolder is a folder rather than a file.

    DrLocator Table
    Signature | Parent | Path | Depth
    AppFile
    AppFolder | AppFile

  3. Finally, populate the AppSearch Table so that the AppSearch Action returns the path of AppFolder. After the installer executes the AppSearch action, the value of MYFOLDER is the full path of AppFolder.

    AppSearch Table (partial)
    Property | Signature
    MYFOLDER | AppFolder


How do I search for a registry entry and create a property holding the value of the registry?

To search for a registry entry and create a property holding the value of that file

  1. Do not add the signature to the Signature table or the CompLocator table. If a file signature is listed in the AppSearch table and is not listed in the Signature or CompLocator tables, the installer looks in the RegLocator table.
  2. Specify the registry entry to be searched for in the RegLocator table. If the signature is absent from the Signature table and the value of the Type column is msidbLocatorTypeRawValue then the search is assumed to be for the particular registry key name pointed to by the RegLocator table.

    RegLocator Table (partial)
    Signature_ | Root | Key | Name | Type
    AppValue | 2 | SOFTWARE\Microsoft\MyApp | Myname | msidbLocatorTypeRawValue

  3. Finally, populate the AppSearch Table so that the AppSearch Action returns the value of AppValue. After the installer executes the AppSearch action, the value of MYREGVAL is the value of AppValue.

    AppSearch Table (partial)
    Property | Signature
    MYREGVAL | AppValue


Checking the Installation of Features, Components, Files

If after running an installation, you need to verify that a particular feature, component, or file has been installed, turn on the verbose logging option during the installation. See Logging and Command Line Options.

The verbose log includes an entry for each feature and component the installation package may install. The log tells what the state of that feature or component was prior to the installation, what state was requested by the installation, and in what state the installer left the feature or component. Feature and component entries in the log appear as the following examples.

MSI (s) (40:A4): Feature: QuickTest; Installed: Absent;   Request:
 Local;   Action: Local
MSI (s) (40:A4): Component: QuickTest; Installed: Absent;   Request:
 Local;   Action: Local

This verbose log indicates that the installation state of the QuickTest feature and component was Absent before running the package, that the package requested a local installation of these, and that the feature and component were both left in the locally installed state after running the package.

The verbose log has an entry for each file that may be installed by the package. The log tells what was done to the file and provides some explanation. File entries in the log appear as in the following example.

MSI (s) (40:A4): File: C:\Test\TESTDB.EXE;  Won't Overwrite;  Existing
 file is of an equal version

This log indicates that the installer will not overwrite the existing Testdb.exe file because the existing file is the same as the version being installed.

Note If you need to author an installation package that searches for an existing file or directory on the user's computer during an installation, use the method described in Searching for Existing Applications, Files, Registry Entries or .ini File Entries.


Installing Permanent Components, Files, Fonts, Registry Keys

To install a file, font, or registry key so that it is not removed when the product is uninstalled, the entire component containing the file, font, or registry key must be made permanent. To make a component permanent, set msidbComponentAttributesPermanent in the Attributes column of the Component table.

Note that the installer removes a registry key after removing the last value or subkey under the key. To prevent an empty registry key from being removed on uninstall, write a dummy value under the key you need keep, and enter + in the Name column of the Registry table.


Removing Stranded Files

If a file that should have been removed from the user's computer remains installed after running an uninstall, the installer may not be removing the component containing the file for one or more of the following reasons:

  • The msidbComponentAttributesPermanent bit was set for the component in the Attributes column of the Component table.
  • No value was entered for the component in the ComponentId column of the Component table.
  • The component is used by another application or feature that is still installed.
  • The key file for the component has a previous reference count under HKLM\Software\Microsoft\Windows\CurrentVersion\SharedDlls.
  • The component is installed in the System Folder and any file in the component has a previous reference count under HKLM\Software\Microsoft\Windows\CurrentVersion\SharedDlls.
  • On Microsoft® Windows® 2000, the installer does not remove any files that are on the Windows File Protection (WFP) list. If a component's key file is on the WFP list of protected files, the installer does not remove the component.


Searching for a Broken Feature or Component

The installer can increase application resiliency by automatically reinstalling damaged components. Specifically, the installer reinstalls a component or feature if it finds that the file or registry key specified in the KeyPath column of the Component table is missing.

If the KeyPath of a feature's component is damaged in the source, or if there is an error in how the KeyPath is authored in the database, the installer may attempt to open an installation package and reinstall the feature each time the feature's shortcut is activated.

To determine the cause of repeated attempts to reinstall a feature or application, check the Event Log for two entries such as the following.

Detection of product 'MyProduct', feature 'MyFeature' failed during
 request for component 'MyComponent'
Detection of product 'MyProduct', feature 'MyFeature', component
 'MyComponent' failed

The first message states which component in the product's package was being installed. This is the component referenced in the Component_ column of the Shortcut table.

The second message states which component is failing detection. This is the component with the missing or damaged KeyPath that's triggering the reinstall.


Replacing Existing Files

Because unnecessary file copying slows an installation, the Windows Installer determines whether the component's key file is already installed before installing the files of any component. If the installer finds a file with the same name as the component's key file installed in the target location, it compares the version, date, and language of the two key files and uses file versioning rules to determine whether to install the component's files provided by the package or to leave the existing files installed. All or none of the files belonging to a component are replaced depending upon the comparison of the key files.

Note that when authoring an installation package with versioned files, the version string in the Version column of the File table must always be identical to the version of the file included with the package.

The default file versioning rules can be overridden or modified by using the REINSTALLMODE property. The installer uses the file versioning rules specified by the REINSTALLMODE property whenever installing, reinstalling, or repairing a file. The following example shows how the installer applies the default File Versioning Rules. The default value of the REINSTALLMODE property is "omus".

The following component key files are installed on the system before the component is reinstalled.

File | Version | Create date | Modified date | Language
FileA | 1.0.0000 | 1/1/99 | 1/1/99 | ENG
FileB | 2.0.0000 | 1/1/99 | 1/1/99 | ENG
FileC | 1.0.0000 | 1/1/99 | 1/1/99 | ENG
FileD | 1.0.0000 | 1/1/99 | 1/2/99 | ENG
FileE | none | 1/1/99 | 1/1/99 | none
FileF (modified > create) | none | 1/1/99 | 1/2/99 | none
FileG | 1.0.0000 | 1/1/99 | 1/1/99 | ENG
FileH | 1.0.0000 | 1/1/99 | 1/1/99 | ENG,FRN,SPN
FileI | 1.0.0000 | 1/1/99 | 1/1/99 | ENG,FRN
FileJ | 1.0.0000 | 1/1/99 | 1/1/99 | ENG,GER,ITN

The following component key files are included in the installer package.

File | Version | Create date | Modified date | Language
FileA (marked same) | 1.0.0000 | 1/1/99 | 1/1/99 | ENG
FileB (earlier version) | 1.0.0000 | 1/1/99 | 1/1/99 | ENG
FileC (later version) | 2.0.0000 | 1/1/99 | 1/1/99 | ENG
FileD (later version) | 2.0.0000 | 12/31/98 | 1/10/99 | FRN
FileE (marked same) | none | 1/1/99 | 1/1/99 | none
FileF (new file) | none | 1/3/99 | 1/3/99 | none
FileG (new language) | 1.0.0000 | 1/1/99 | 1/1/99 | FRN
FileH (new language) | 1.0.0000 | 1/1/99 | 1/1/99 | ITN,ENG,GER
FileI (more languages) | 1.0.0000 | 1/1/99 | 1/1/99 | ENG,FRN,SPN
FileJ (fewer languages) | 1.0.0000 | 1/1/99 | 1/1/99 | GER

The following component key files stay on the system after the component is reinstalled. The state of the key file determines the state of any other files in the component.

File | Version | Create date | Modified date | Language
FileA (original) | 1.0.0000 | 1/1/99 | 1/1/99 | ENG
FileB (original) | 2.0.0000 | 1/1/99 | 1/1/99 | ENG
FileC (replacement) | 2.0.0000 | 1/1/99 | 1/1/99 | ENG
FileD (replacement) | 2.0.0000 | 12/31/98 | 1/10/99 | FRN
FileE (replacement) | none | 1/1/99 | 1/1/99 | none
FileF (original) | none | 1/1/99 | 1/2/99 | none
FileG (replacement) | 1.0.0000 | 1/1/99 | 1/1/99 | FRN
FileH (replacement) | 1.0.0000 | 1/1/99 | 1/1/99 | ITN,ENG,GER
FileI (replacement) | 1.0.0000 | 1/1/99 | 1/1/99 | ENG,FRN,SPN
FileJ (original) | 1.0.0000 | 1/1/99 | 1/1/99 | ENG,GER,ITN


Editing Installer Shortcuts

The Shortcut table holds the information the application needs to create installer shortcuts on the user's computer. Installer shortcuts support installation-on-demand and advertisement. Note that you cannot edit the properties of installer shortcuts as you can in the case of regular shortcuts.

Setting the DISABLEADVTSHORTCUTS property disables the generation of installer shortcuts and specifies that these shortcuts should instead be replaced by regular shortcuts.


Installing from Terminal Server

Administrator and non-administrator users can perform installations from the Terminal Services console.

Setting the EnableAdminTSRemote policy on Windows Installer version 1.1 enables administrators to perform installations from Terminal Services client sessions. An administrator installing from a Terminal Services client-session can do administrative installations.

Non-administrators cannot do any installations from a client-session. For more information, see Terminal Services in the Platform SDK.

See Also

EnableAdminTSRemote, TerminalServer property, RemoteAdminTS property


Using Isolated Components

By using isolated components, authors of installation packages can specify that the installer copy the shared files of an application directly into the application's folder rather than to a shared location. This private set of files are then used exclusively by the application.

For more information, see:

Installing a COM component to a private location

Installing a non-COM component to a private location

Make a COM component in an existing package private

Make a non-COM component in an existing package private


Installing a COM Component to a Private Location

To force a COM-client application to always use the same copy of a COM-server, author the application's installation package to specify an isolated components relationship between the COM server and client. This installs a private copy of the COM-server component to a location used exclusively by the client application. Do the following when authoring the package:

  • Put the COM server DLL and the .exe client in separate components.
  • Enter a record in the IsolatedComponent table with the COM-client component in the Component_Shared column and the client application in the Component_Application column. Include the IsolateComponents action in the sequence tables.
  • Set the msidbComponentAttributesSharedDllRefCount bit in the Component table record for Component_Shared. The installer requires this global refcount on the shared location to protect the shared files and registration in cases where there is sharing with other installation technologies.
  • Windows Installer version 1.1 is required.


Installing a non-COM Component to a Private Location

To force a client application to always use the same copy of a non-COM server, author the application's installation package to specify an isolated components relationship between the server and client. This installs a private copy of the server component to a location used exclusively by the client application. Do the following when authoring the package:

  • Put the server DLL and the .exe client in separate components.
  • Enter a record in the IsolatedComponent table with the client component in the Component_Shared column and the client application in the Component_Application column. Include the IsolateComponents action in the sequence tables.
  • Set the msidbComponentAttributesSharedDllRefCount bit in the Component table record for Component_Shared. The installer requires this global refcount on the shared location to protect the shared files and registration in cases where there is sharing with other installation technologies.
  • Avoid authoring a shared registered path across components.
  • Use Windows Installer version 1.0 or later.


Make a COM Component in an Existing Package Private

An administrator can force a COM-client application to always use the same copy of a COM-server in an existing package, without affecting other applications, by specifying an isolated components relationship between the COM server and client. This installs a private copy of the COM-server component to a location used exclusively by the client application. The administrator needs to use transforms or an a package authoring tool to do the following:

  • Put the COM server DLL and the .exe client in separate components.
  • Enter a record in the IsolatedComponent table with the COM-client component in the Component_Shared column and the client application in the Component_Application column. Include the IsolateComponents action in the sequence tables.
  • Set the msidbComponentAttributesSharedDllRefCount bit in the Component table record for Component_Shared. The installer requires this global refcount on the shared location to protect the shared files and registration in cases where there is sharing with other installation technologies.
  • Windows Installer version 1.1 is required.


Make a non-COM Component in an Existing Package Private

An administrator can force a client application to always use the same copy of a non-COM server in an existing package, without affecting other applications, by specifying an isolated components relationship between the server and client. This installs a private copy of the server component to a location used exclusively by the client application. The administrator needs to use transforms or an a package authoring tool to do the following:

  • Put the server DLL and the .exe client in separate components.
  • Enter a record in the IsolatedComponent table with the client component in the Component_Shared column and the client application in the Component_Application column. Include the IsolateComponents action in the sequence tables.
  • Set the msidbComponentAttributesSharedDllRefCount bit in the Component table record for Component_Shared. The installer requires this global refcount on the shared location to protect the shared files and registration in cases where there is sharing with other installation technologies.
  • Windows Installer version 1.1 is required.

Note that if no shared registered paths have been authored across components, Windows Installer version 1.1 may not be required. In this case, the administrator could just alter the Directory and Component tables such that the files of Component_Shared get installed to the same folder as Component_Application.


How do I specify a per-user or per-machine installation?

On Microsoft® Windows® 2000 and Microsoft Windows NT®, the installer performs a per-user or per machine installation depending on the value of the ALLUSERS property.

If ALLUSERS is not set, the installer does a per-user installation. If the ALLUSERS property is set to 1, the installer attempts a per-machine installation. The per-machine installation succeeds only if the user has administrative access privileges on the computer. If ALLUSERS is set to 2, the installer first attempts a per-machine installation. In this case, the per-machine installation succeeds only if the user has administrative access privileges on the computer, otherwise the installer does a per-user installation. If ALLUSERS is set to 2, the installer always resets ALLUSERS property to null or 1 based upon whether it determines to do a per-user or a per-machine installation.

On Microsoft® Windows® 95 and Windows 98, the installation is per user or per machine depending upon operating system configuration. If Profiles are on and the Start menu is per-user, the installer does a per user installation. If Profiles are on and Start menu is shared, the installer does a per-machine installation. If Profiles are not on and Start menu is shared, then the installer does a per-user installation. The installer always resets the ALLUSERS property to null or 1 based on whether it determines to do a per-user or a per-machine installation.

For more information, see Per-User Installations and Per-Machine Installations.


How do I install a COM+ application with the Windows Installer?

For information about how to install COM+ applications, see Deploying COM+ Applications in the COM+ section of the Platform SDK.

The following actions and table for installing COM+ applications are available in Windows Installer version 1.1 and not available in Windows Installer version 1.0:

RegisterComPlus action

UnregisterComPlus action

Complus table


How do I add or remove registry keys on the installation or removal of components?

The installer can add or remove registry values once all selected components and their related files have been installed. For more information, see the following:

Modifying the Registry

Registry Table

RemoveRegistry Table

How do I add and remove an application and leave no trace in the registry?


How do I add and remove an application and leave no trace in the registry?

If an application needs to be registered, author the installation package as described in the section How do I add or remove registry keys on the installation or removal of components? Registration is used by the installer for advertisement and by the Add/Remove in the control panel. If an application is not registered, it cannot be advertised and is not listed in the Add/Remove control panel.

You may omit registering an application by removing the RegisterProduct action, RegisterUser action, PublishProduct action, and PublishFeatures action from the InstallExecuteSequence table and AdvtExecuteSequence table. All these actions must be removed or some trace of the application may remain in the registry. Removing all of these actions prevents the application from being listed in Add/Remove in the control panel and prevents the advertisement of the application.


How do I reduce the size of my .msi file?

Developers of Windows Installer packages may notice their .msi files getting larger than expected after repeated edits and saves. Windows Installer .msi files are compound files containing storages and streams and have some of the same storage limitations as OLE document files. If you edit and save the same .msi file over and over, it creates wasted storage space in the file. This only affects authors of .msi files and has no effect on Windows Installer users. Developers may want to remove this wasted storage space before shipping their final .msi file.

To remove wasted storage space and reduce the final size of .msi files, authors have two options.

  • Export all the tables in the database to .idt files and then import these into a new database. This produces the most compact storage possible.
  • Use a software utility for compacting the storage space of OLE document files.


How do I install a package with elevated privileges as a non-admin?

An application is called a "managed application" if elevated (system) privileges are used to install the application. There are three methods by which an administrator can enable a non-administrator user to install managed applications.

  • On Windows NT 4.0 or Windows 2000, an administrator can set the AlwaysInstallElevated registry keys for both per-user and per-machine installations on the computer. For more information, see AlwaysInstallElevated. Note that this method can open the computer to a security risk because once an administrator with elevated privileges has set these registry keys, non-administrator users can run installations with elevated privileges and access secure locations on the computer, such as the SystemFolder or HKLM registry key.
  • On Windows NT 4.0 or Windows 2000, an administrator can install or advertise the package on the computer for a per-machine installation. See Per-Machine Installations and How do I specify a per-user or per-machine installation? The Windows Installer always has elevated privileges while doing per-machine installations. The administrator uses elevated privileges to advertise the package. If a non-administrator user then installs the application the installation can run with elevated privileges. Non-administrator users still cannot install unadvertised packages that require elevated system privileges. For more information, see Advertisement.
  • On Windows 2000, an administrator can advertise an application on a user's computer by assigning or publishing the Windows Installer package using application deployment and Group Policy. The administrator uses elevated privileges to advertise the package for per-machine. If a non-administrator user then installs the application, the installation can run with elevated privileges. Non-administrator users still cannot install unadvertised packages that require elevated system privileges.


How do I change the target location for a directory?

If it is possible to do so, the best way to specify the target location for a directory is by authoring the Directory Table in your installation package to provide the correct location. See Using the Directory Table.

If it is necessary to change the directory location at the time of the installation you have the following options:

  • Specify the location of a directory by setting the value of a public property on the command line. During the CostFinalize action the internal directory paths used by the installer are updated to the value of properties listed as keys in the Directory table. See Using Properties and Setting Public Property Values on the Command Line.
  • Specify the location of a directory using a custom action. If the custom action is to run before the CostFinalize action, you can use a Custom Action Type 51 to set the value of a property from a formatted text string. If the custom action runs after CostFinalize, you can use a Custom Action Type 35 to set the value of the directory path from a formatted text string.
  • If the installation is running a full UI, you may use the SetTargetPath ControlEvent to set the directory path.


Windows Installer on 64-bit Operating Systems

[This is preliminary documentation and subject to change.]

On 64-bit operating systems, Microsoft® Windows® Installer version 1.5 installs and manages applications consisting of 32-bit or 64-bit Windows Installer components. The following sections describe Windows Installer on 64-bit systems.

About Windows Installer on 64-Bit Operating Systems

Using 64-Bit Windows Installer Packages


About Windows Installer on 64-Bit Operating Systems

[This is preliminary documentation and subject to change.]

Microsoft® Windows® Installer version 1.5 runs as a service on computers using 32-bit or 64-bit Windows. Versions of the installer earlier than version 1.5 can install and manage 32-bit Windows Installer Packages only on 32-bit operating systems. Windows Installer version 1.5 supports virtually all of the setup functionality available with earlier installer versions. Note that you cannot advertise or install a 64-bit application on a 32-bit operating system.

A Windows Installer package must be specified as either a 32-bit or a 64-bit package; it cannot be specified as neutral. On a computer using a 64-bit operating system, the Windows Installer service is hosted in a 64-bit process that installs both 32-bit and 64-bit packages. Windows Installer version 1.5 installs three types of Windows installer packages on a computer running a 64-bit operating system:

  • 32-bit packages that contain only 32-bit components.
  • 64-bit packages containing some 32 bit components.
  • 64-bit packages containing only 64 bit components.

The follow sections describe the two types of Windows Installer packages and the new installer properties provided by Windows Installer version 1.5 for 64-bit packages.

32-bit Windows Installer Packages

64-bit Windows Installer Packages


32-bit Windows Installer Packages

[This is preliminary documentation and subject to change.]

A 32-bit package consists of only 32-bit Windows Installer components and must have the value "Intel" (or "Alpha" for Windows Installer version 1.0) entered in the platform field of the Template Summary Property.

For more information, see Windows Installer on 64-bit Operating Systems and 64-bit Windows Installer Packages.


64-bit Windows Installer Packages

[This is preliminary documentation and subject to change.]

A 64-bit package consists partially or entirely of 64-bit Windows Installer components. The following is required for every 64-bit Windows Installer Package:

  • The value "Intel64" must be entered in the platform field of the Template Summary property.
  • The Page Count Summary Property must be set to the integer 150 because Windows Installer version 1.5 is the minimum version capable of installing 64-bit components.
  • Each 64-bit Windows Installer component in the package must include the msidbComponentAttributes64bit bit in the Attributes column of the Component table.

For more information, see Windows Installer on 64-bit Operating Systems and 32-bit Windows Installer Packages.


Using 64-Bit Windows Installer Packages

[This is preliminary documentation and subject to change.]

Setup developers should do the following when creating 64-bit Windows Installer Packages or applications that call the Windows Installer to install 64-bit packages:

  • Use a Windows Installer database schema of 150 or higher. Specify that version 1.5 is the minimum version of the Windows Installer required to install the package by setting the Page Count Summary Property to the integer 150. Earlier Windows Installer versions reject attempts to install 64-bit packages.
  • Indicate in the package's summary information stream that this is a 64-bit package. Enter "Intel64" into the platform field of the Template Summary Property. A package cannot be neutral, and this summary property must never have "Intel64" entered together with "Intel" (or "Alpha" for Windows Installer version 1.0).
  • Identify every 64-bit component by setting the msidbComponentAttributes64bit in the Attributes column of the Component table.
  • Use optional conditional statements that check the version of the 64-bit operating system by referencing the VersionNT64 property. Windows Installer version 1.5 sets this property to the 64-bit Windows version and leaves VersionNT64 undefined if the operating system is not 64-bit Windows. For details, see Using Properties in Conditional Statements.
  • Use optional conditional statements that check the numeric processor level of the computer by referencing the Intel64 property. Windows Installer version 1.5 sets this property to the current numeric processor level of the computer and leaves Intel64 undefined if this is not an IA-64 processor. For details, see Using Properties in Conditional Statements.
  • Use the AppSearch table and AppSearch action to do optional searches of the registry for existing 64-bit components. To search for existing 64-bit components, include the msidbLocatorType64bit bit in the Type column of the RegLocator table. For details, see Searching for Existing Applications, Files, Registry Entries or .ini File Entries
  • Obtain the paths to system folders by referencing the System64Folder property, ProgramFiles64Folder property, and CommonFiles64Folder property for the 64-bit folders and the SystemFolder property, ProgramFilesFolder property, and CommonFilesFolder property for the 32-bit folders.
  • Verify that the application uses the correct GUID when referencing a 64-bit component. If there are 32-bit and 64-bit versions of particular component, these should have different component ID GUIDs.
  • Determine whether any new environment variables need to be defined when installing 64-bit applications.
  • Verify that the application only calls 32-bit services that run as executables. Applications should not call 32-bit services that run in DLLs.
  • If the application installs coexisting 32-bit and 64-bit versions of a component, verify that the application share .ini file information correctly.
  • Verify that the application only applies 32-bit patches to 32-bit binaries and 64-bit patches to 64-bit binaries.
  • Application developers should consider future upgrade scenarios for both 32-bit and 64-bit versions and maintain upgrade codes. For details, see Patching and Upgrades.

For more information, see 64-Bit Custom Actions.


64-Bit Custom Actions

[This is preliminary documentation and subject to change.]

Windows Installer version 1.5 uses binary custom actions, Executable files and Dynamic-Link Libraries that have been compiled for 64-bit operating systems. No special authoring of the installation package is required to use 64-bit custom actions.


Assemblies

[This is preliminary documentation and subject to change.]

Windows Installer version 1.5 can install and manage common language runtime assemblies and Win32 assemblies. Developers of Windows Installer packages have the option of installing assemblies to the global assembly cache or to a location that is isolated for a particular application. This improved capability to isolate applications is an important part of the Microsoft® .NET Framework.

The following sections describe common language runtime assemblies:

About Assemblies

Using Assemblies

Reinstallation Modes of Microsoft .NET Framework Assemblies

For information about installing COM and COM+ 1.0 applications see:

How do I install a COM+ application with the Windows Installer?

Installing a COM Component to a Private Location

Make a COM Component in an Existing Package Private


About Assemblies

[This is preliminary documentation and subject to change.]

Windows Installer has the following features which are related to Microsoft® .NET Framework common language runtime assemblies and Win32 assemblies. Authors of Windows Installer packages can utilize these features by populating the MsiAssembly table and MsiAssemblyName table.

  • Installation, repair, or removal of Microsoft .NET Framework assemblies and Win32 assemblies in the global assembly cache.
  • Installation, repair, or removal of Microsoft .NET Framework assemblies and Win32 assemblies in private locations designated for particular applications.
  • Roll back of unsuccessful installations, repairs, or removals of Microsoft .NET Framework assemblies and Win32 assemblies.
  • Install-on-demand of Microsoft .NET Framework assemblies that are advertised by a strong name in the global assembly cache.
  • Install-on-demand of Microsoft .NET Framework assemblies and Win32 assemblies in private locations designated for particular applications.
  • Patching of Microsoft .NET Framework assemblies and Win32 assemblies.
  • Advertisement of shortcuts that point to Microsoft .NET Framework assemblies and Win32 assemblies.

For more information, see Using Assemblies.


Using Assemblies

[This is preliminary documentation and subject to change.]

A Microsoft .NET Framework assembly or Win32 assembly is handled by the Windows Installer as a single Windows Installer component. All of the files that constitute an assembly must be contained by a single Windows Installer component that is listed in the Component table.

When installing a Microsoft .NET Framework assembly or Win32 assembly to an isolated location for a particular application, the application must be specified in the File_Application column of the MsiAssembly table. This field is a key into the File table. The installer uses the directory structure specified in the Directory table to install the assembly into the same directory as the component containing this file.

When installing a Microsoft .NET Framework assembly or Win32 assembly to the global assembly cache, the value in the Component_Applications column of the MsiAssembly table must be Null. The following sections describe the installation of assemblies to the global assembly cache.

Installation of Assemblies to the Global Assembly Cache

Rollback of Assemblies in the Global Assembly Cache

Removal of Assemblies from the Global Assembly Cache


Installation of Assemblies to the Global Assembly Cache

[This is preliminary documentation and subject to change.]

The Windows Installer installs Microsoft .NET Framework assemblies into the global assembly cache using Microsoft .NET Framework. When installing assemblies to the global assembly cache, the installer cannot use the same directory structure and file versioning rules it uses when installing regular Windows Installer components. Regular Windows Installer components may be installed into multiple directory locations by different products. Assemblies can exist only once in the assembly cache. Assemblies are added and removed from the assembly cache atomically, and so the files comprising an assembly are always installed or removed together.

The disk cost of regular Windows Installer components and Microsoft .NET Framework assemblies are calculated differently. The total disk cost of a regular Windows Installer component includes local costs, source costs, and removal costs. For details, see File Costing. This method cannot be used to cost Microsoft .NET Framework assemblies because these may have clients other than the Windows Installer. The cost of Microsoft .NET Framework assemblies must be determined by querying the Microsoft .NET Framework Common Language Runtime.

The Windows Installer uses a two-step transactional process to install products containing Microsoft .NET Framework assemblies. This enables the rollback of assembly installation and removal. For more information, see Rollback of Assemblies in the Global Assembly Cache.


Rollback of Assemblies in the Global Assembly Cache

[This is preliminary documentation and subject to change.]

A two step process extends the Windows Installer's transaction model to products containing Microsoft .NET Framework Common Language Runtime assemblies. This enables the installer to rollback unsuccessful installations and removals of assemblies.

During the first step, the Windows Installer uses the Microsoft .NET Framework to create one interface for each assembly. The Windows Installer uses as many interfaces as there are assemblies being installed. Committing an assembly using one of these interfaces only means that the assembly is ready to replace any existing assembly with the same name, it does not yet replace it. If the user cancels the installation, or if there is a fatal installation error, the Windows Installer can still rollback the assembly to its previous state by releasing these interfaces.

After the Windows Installer completes installing all assemblies and Windows Installer components, the installer may initiate the second step of the installation. The second step uses a separate function to do the final commit of all the new Microsoft .NET Framework assemblies. This replaces any existing assemblies with the same name.


Removal of Assemblies from the Global Assembly Cache

[This is preliminary documentation and subject to change.]

The Windows Installer determines whether to allow the removal of a Microsoft .NET Framework assembly based upon a client list it keeps independently of the assembly. The Windows Installer keeps one pin bit to represent Windows Installer clients of the assembly. The installer pins the assembly for the first Windows Installer client and unpins it when the last Windows Installer client is removed. The assembly maintains a pin bit for every client of an assembly.

The Windows Installer is not directly responsible for the physical removal of Microsoft .NET Framework assemblies from the computer. The installer unpins the assembly when the last Windows Installer client is removed. If the Windows Installer is the last client of the assembly, the Microsoft .NET Framework provides the option to force a synchronous cleanup of the assembly. The cleanup process is atomic and there is no provision for a "rollback" at this point. All unpinning of Microsoft .NET Framework assemblies must occur after the user has had a chance to cancel the installation or removal.


Reinstallation Modes of Microsoft .NET Framework Assemblies

[This is preliminary documentation and subject to change.]

Microsoft .NET Framework assemblies that are installed to the global assembly cache must have identical files in all occurrences of the assembly. This means that the reinstallation modes used by MsiReinstallFeature and MsiReinstallProduct must have different meanings for regular components and Microsoft .NET Framework assemblies. The following definitions of reinstall modes apply to Microsoft .NET Framework assemblies.

Reinstall mode | Meaning for Microsoft .NET Components
REINSTALLMODE_FILEMISSING | Install or reinstall the Common Language Runtime component if it is missing or incomplete.
REINSTALLMODE_FILEOLDERVERSION | Install or reinstall the Common Language Runtime component if it is missing or incomplete.
REINSTALLMODE_FILEEQUALVERSION | Install or reinstall the Common Language Runtime component if it is missing or incomplete.
REINSTALLMODE_FILEEXACT | Install or reinstall the Common Language Runtime component if it is missing or incomplete.
REINSTALLMODE_FILEVERIFY | Install or reinstall the Common Language Runtime component if it is missing or if the existing component is incomplete or corrupt.
REINSTALLMODE_FILEREPLACE | Always install or reinstall the Common Language Runtime component.
REINSTALLMODE_USERDATA |
REINSTALLMODE_MACHINEDATA |
REINSTALLMODE_SHORTCUT |
REINSTALLMODE_PACKAGE |


Digital Signatures and Windows Installer

[This is preliminary documentation and subject to change.]

The Windows Installer version 1.5 can use digital signatures as a means to detect corrupted resources. A signer certificate may be compared to the signer certificate of an external resource to be installed by the package. Windows Installer version 1.5 can only verify the digital signatures of external cabinets, and only by the use of the MsiDigitalSignature table and MsiDigitalCertificate table.

When the Windows Installer version 1.5 or later installs a file stored in an external cabinet, it does the following.

  • The installer checks to see if the media entry for that external cabinet is listed in the MsiDigitalSignature table. A file that is stored in an external cabinet is identified by having an entry in the Cabinet column of the Media table that is not prefixed by a '#' character.
  • Before opening the external cabinet, the installer calls WinVerifyTrust to extract the current certificate and hash information. If there is a mismatch between the current signature information on the cabinet and the signature information authored in the package, the install fails. The installation fails because the cabinet may have been compromised and cannot be trusted.

For more information regarding the use of digital signatures, digital certificaties, and WinVerifyTrust, see the Security section of the Microsoft® Platform Software Development Kit (SDK).

For more information see MsiGetFileSignatureInformation, MsiDigitalCertificate table, and MsiDigitalSignature table.


Installer Functions

The following sections describe function calls to the Microsoft® Windows® Installer API.

About Installer Functions

Using Installer Functions

Installer Function Reference


About Installer Functions

The Microsoft® Windows® Installer allows system administrators to install, update, and remove components.

For more information about adding installer functionality, see Using Installer Functions.


Using Installer Functions

To add Microsoft® Windows® Installer functionality to your application, you can use the installer service functions. Because the installer is a setup utility and a component management system, an application that uses the installer must incorporate the installer service functions as part of its normal operation. The following topics include procedures that explain how to implement installer functionality in your application:

  • Initializing an Application
  • Getting Application Information
  • Requesting a Feature
  • Installing an Application
  • Reinstalling a Feature or Application
  • Removing an Advertised Application
  • Working with Features and Components
  • Installing a Missing Component


Initializing an Application

To enable installer functionality, an application must call a number of functions when it is initializing. For more information, see Installation Mechanism. The following steps describe how to use the installer to initialize an application:

To initialize an application

  1. Call the MsiGetProductCode function so the application can identify itself to the installer.

    The product code is a required parameter for many installer functions.

  2. Call the MsiGetUserInfo function to collect user information the first time the application starts.

    If the call to MsiGetUserInfo fails, call the MsiCollectUserInfo function to collect user information.

  3. Display a default user interface, if necessary, by calling the MsiSetInternalUI function.

    To author your own user interface, register it with the installer by calling the MsiSetExternalUI function.

  4. Call the MsiEnableLog function to set the logging level.
  5. Present the user with available features by enumerating the features of your application. You can enumerate features in the following ways:
    • Query the installer feature-by-feature. For example, before the application draws a button or a menu item, the application calls the MsiQueryFeatureState function so the installer can check that the feature is available.
    • Enumerate all of the available features at once by calling the MsiEnumFeatures function. To use this function, the application must call MsiEnumFeatures repeatedly while incrementing an index.
  6. Get detailed information about the current installation by calling the following enumeration functions repeatedly, incrementing an index variable for each call:
    • Call the MsiEnumProducts function to enumerate products registered with the installer.
    • Call the MsiEnumComponents function to enumerate components.
    • Call the MsiEnumComponentQualifiers function to enumerate component qualifiers.
    • Call the MsiEnumClients function to enumerate the products for a particular component.

    If the return value on an enumeration function is ERROR_SUCCESS, there are still more items to be enumerated and the function should be called again with an incremented index variable. If the return value is ERROR_NO_MORE_ITEMS, then all of the items have been enumerated, and the function should not be called again.


Getting Application Information

The product database contains information about a product. For more information on obtaining product information with enumeration functions, see Initializing an Application.

To get product information

  1. Verify that a product is installed by calling the MsiQueryProductState function.
  2. Open the database and obtain a handle to it by calling the MsiOpenProduct function.

    If the database is contained in an installation package, call the MsiOpenPackage function.

  3. Use the open handle to obtain product properties with the MsiGetProductProperty function, and to obtain descriptive feature information with the MsiGetFeatureInfo function.

    If you want to obtain product information using the product code, rather than using the open database handle, call the MsiGetProductInfo function instead of MsiGetProductProperty.

  4. Close an open installation handle by calling the MsiCloseHandle function.

    The MsiCloseAllHandles function is a diagnostic function and should not be used to close handles you know to be open. It is acceptable to call the MsiCloseAllHandles function when the application closes to ensure that all handles have been closed.


Requesting a Feature

There are several functions an application must call to request features. Before requesting a feature, the application must ensure that the feature is installed. If the application calls MsiUseFeature before the application accesses a feature, the application can use the information returned to maintain usage metrics.

To request a feature

  1. Call the MsiEnumFeatures or the MsiQueryFeatureState function if you want to determine the availability of a feature without incrementing the usage count.
  2. Indicate your application's intent to use a feature by calling the MsiUseFeature function.
  3. Determine file locations by calling the MsiGetComponentPath function.
  4. Configure the feature by calling the MsiConfigureFeature function.
  5. Obtain usage metrics that your application can use by calling the MsiGetFeatureUsage function.

The following diagram illustrates the feature request model.


Installing an Application

You can install entire products with Windows Installer functions. The following steps describe how to install a product.

To install a product

  1. Run a product through its installation or uninstallation sequence by calling the MsiInstallProduct function.
  2. Specify the installation level by calling the MsiConfigureProduct function.

    You can use the parameters of the MsiConfigureProduct function to set the installation state (for example, installed locally; installed to run from the source, etc.) and level, such as the range of product features to be included.

For more information about installing an application, see Resiliency and Installation Mechanism.


Reinstalling a Feature or Application

Windows Installer can repair, replace, and verify files contained in an application. A partial or complete application reinstallation might be required if any files or registry entries associated with any feature have become corrupted or are missing.

When a feature or application is reinstalled, all the services, environment variables, and custom actions belonging to the feature or application are reinstalled as well. Note that this means that any changes made to environment variables between the original installation and the reinstallation are lost.

The following list contains methods of reinstalling a feature or product. The first two methods have been automated by the installer:

  • Repair, replace, or verify files by calling the MsiReinstallFeature function.
  • Reinstall the entire product by calling the MsiReinstallProduct function.
  • Reinstall, replace, or verify files with an Installer UI control button via the Reinstall ControlEvent.
  • Reinstall, replace, or verify files from a command line by setting the REINSTALL property and the REINSTALLMODE property.

For more information on reinstalling a feature or application, see Resiliency.

To reinstall a product using the installer

Call MsiReinstallProduct.

To reinstall a feature using the installer

Call MsiReinstallFeature.

To reinstall a product or feature with an installer user interface

  1. Add a button to the specified dialog box by adding an entry to the Control table.
  2. Add a ReinstallMode ControlEvent to the ControlEvent table, with the Dialog_ and Control_ fields referencing the button control you created in step 1. In the Argument field, enter a string containing the letters corresponding to the reinstall modes you want (the acceptable values for this field are identical to those accepted for the REINSTALLMODE property). The value in the Ordering column for this event should be 1.
  3. Add a Reinstall ControlEvent event to the ControlEvent table, again referencing the same button control. The Argument field for this event will normally be "ALL", to force reinstallation of all features, but you can place the name of a specific feature here. The value in the Ordering column for this event should be 2.
  4. Add one more event tied to the same button control, to actually initiate the reinstallation. This can be an EndDialog event (with an argument of Return). More typically, however, a NewDialog event would be used here to jump to an Are you sure you want to reinstall? confirmation dialog box. The value in the Ordering column for this event should be 3.

    If desired, several Reinstall buttons can be created for a single dialog box, allowing the user to select the type of reinstallation performed. In this case, each button is authored as outlined in the preceding procedure, with a different ReinstallMode ControlEvent parameter for each button.

To reinstall a product or feature from a command line

Once a particular product has been installed (with some or all of the product's features), a reinstallation can be performed at the command line.

  1. From the command prompt, specify the REINSTALL property.
  2. From the command prompt, specify the REINSTALLMODE property.

    Specifying these properties allows the user to reinstall any or all of the product's features. The type of reinstallation can also be specified. For example, you can specify that only those files that are completely missing should be reinstalled, or that only corrupt files (for example, any executable file whose checksum doesn't match the actual file contents) be replaced.


Removing an Advertised Application

To remove an application that has been installed in the advertised state, simply uninstall it using MsiInstallProduct or MsiConfigureProduct. You can also remove an advertised application from the command line. See Command Line Options.

Note that you may be unable to remove an advertised application if you have authored the package in such a way that running an installation is conditional upon the statement NOT Installed. An advertised application is not installed on the user's computer and the installer does not set the Installed Property. The package must be authored so that advertised applications can be uninstalled.


Working with Features and Components

There are several functions that change the installation of product components and features. The following describes how to change features and components.

To change the installation of features and components

  1. Set the installation level for a component or feature by calling the MsiSetInstallLevel function.

    Each feature in a package is assigned an installation level in the Feature table. If the installation level of a feature is lower than the level set by MsiSetInstallLevel, the feature is selected for installation. After MsiSetInstallLevel is called, you can explicitly change whether a feature is installed.

  2. Determine which states are available for a specified feature by calling the MsiGetFeatureValidStates function.
  3. Obtain the disk space requirements for a specified feature and its child features by calling the MsiGetFeatureCost function.
  4. Obtain the current state of a feature or component by calling the MsiGetFeatureState function or the MsiGetComponentState function.
  5. Change the state of the feature or component with the MsiSetFeatureState function or the MsiSetComponentState function.


Installing a Missing Component

You can use the Microsoft® Windows® Installer to detect missing components or files and to then reinstall features containing the missing components. Because the installer installs features, and not components, it must first resolve to which component a missing file belongs and then install the feature containing that component. If more than one feature is linked to that component, the installer installs the feature requiring the least disk space.

Calling MsiGetComponentPath verifies that the key file of a component is present; however, it is still possible that other files belonging to the component are missing. In this case, call MsiInstallMissingFile. The installer then resolves to which component the file belongs and installs the feature that is linked to the component that requires the least disk space.

If the MsiGetComponentPath function unexpectedly fails, you must install missing components. The following describes how to install missing components.

To detect and install a missing component

  • Call MsiGetComponentPath to verify that the key file of a component is present. However, even if the key file of the component is present, it is still possible that other files belonging to the component are missing.
  • Call the MsiInstallMissingComponent function if the feature associated with the component is unknown.
  • Call the MsiConfigureFeature or MsiProvideComponent function if the feature associated with the component is known.
  • Call MsiInstallMissingFile if an application is unable to open a file.


Installer Function Reference

To enable the Microsoft® Windows® Installer in your application, you must use the installation functions. This topic lists these functions by category.

User Interface and Logging Functions

Function name | Brief description of function
MsiSetInternalUI | Enables the installer's internal user interface.
MsiSetExternalUI | Enables an external user-interface handler.
MsiEnableLog | Sets the log mode for all installations in the calling process.

Handle Management Functions

Function name | Brief description of function
MsiCloseHandle | Closes an open installation handle.
MsiCloseAllHandles | Closes all open installation handles. Not to be used for cleanup.

Installation and Configuration Functions

Function name | Brief description of function
MsiInstallProduct | Installs or removes an application or application suite.
MsiConfigureProduct | Installs or removes an application or application suite.
MsiConfigureProductEx | Installs or removes an application or application suite. A product command line may be specified.
MsiReinstallProduct | Reinstalls or repairs an installation.
MsiConfigureFeature | Configures the installed state of a feature.
MsiReinstallFeature | Validates or repairs features.
MsiInstallMissingComponent | Installs missing components.
MsiInstallMissingFile | Installs missing files.
MsiSourceListAddSource | Adds a source to the list of network sources.
MsiSourceListClearAll | Removes all network sources from the source list.
MsiSourceListForceResolution | Forces the installer to search the source list to locate a source.

Component-Specific Functions

Function name | Brief description of function
MsiProvideComponent | Installs and returns full component path of a component.
MsiProvideQualifiedComponent | Installs and returns full component path of a qualified component.
MsiProvideQualifiedComponentEx | Installs and returns full component path of a qualified component that is published by a product.
MsiGetComponentPath | Returns full path or registry key to an installed component.
MsiLocateComponent | Returns full path to an installed component without a product code.

Application-Only Functions

Function name | Brief fescription of function
MsiCollectUserInfo | Stores user information from an installation wizard.
MsiUseFeature | Increments usage count for a feature and indicates installation state.
MsiUseFeatureEx | Increments usage count for a feature and indicates installation state.
MsiGetProductCode | Returns product code using the component code.

System Status Functions

Function name | Brief description of function
MsiEnumProducts | Enumerates advertised products.
MsiEnumRelatedProducts | Enumerates currently installed products having a specified upgrade code.
MsiEnumFeatures | Enumerates published features.
MsiEnumComponents | Enumerates the installed components.
MsiEnumClients | Enumerates the clients of an installed component.
MsiEnumComponentQualifiers | Enumerates the advertised qualifiers for a component.
MsiQueryFeatureState | Returns the installed state of a feature.
MsiQueryProductState | Returns the installed state for an application or application suite.
MsiGetFeatureUsage | Returns usage metrics for a feature.
MsiGetProductInfo | Returns product information for published and installed products.
MsiGetUserInfo | Returns registered user information for an installed product.

Product Query Functions

Function name | Brief description of function
MsiOpenProduct | Opens a product for use with the functions that access the database.
MsiOpenPackage | Opens a package for use with the functions that access the database.
MsiGetProductProperty | Retrieves properties in the product database.
MsiGetFeatureInfo | Returns descriptive information for a feature.
MsiVerifyPackage | Verifies that the specified file is an installation package.

Patching Functions

Function name | Brief description of function
MsiApplyPatch | Invokes an installation and applies a patch package.
MsiEnumPatches | Returns the GUID for each patch that has been applied to a product and a list of transforms from each patch that apply to the product.
MsiGetPatchInfo | Returns information about a patch.

File Query Functions

Function name | Brief description of function
MsiGetFileHash | Takes the path to a file and returns a 128-bit hash of that file. Available with Windows Installer version 1.5 and later versions.
MsiGetFileSignatureInformation | Takes the path to a file that has been digitally signed and returns the file's signer certificate and hash. Available with Windows Installer version 1.5 and later versions.
MsiGetFileVersion | Returns the version string and language string.

Database Functions

In addition to the installer functions listed above, you can manipulate information in the installation database by using the database access functions described in the Database Functions section.


MsiApplyPatch

For each product listed by the patch package as eligible to receive the patch, the MsiApplyPatch function invokes an installation and sets the PATCH property to the path of the patch package.

UINT MsiApplyPatch(
  LPCTSTR szPatchPackage,    // location of the patch package
  LPCTSTR szInstallPackage,  // location of product to be patched
                             // <optional>
  INSTALLTYPE eInstallType,  // type of install to patch
  LPCTSTR szCommandLine      // command line <property settings>
);

Parameters

szPatchPackage
Specifies the full path to the patch package.
szInstallPackage
Specifies a path to the product that is to be patched if eInstallType is set to INSTALLTYPE_NETWORK_IMAGE. The installer applies the patch to every eligible product listed in the patch package if szInstallPackage is set to 0 and eInstallType is set to INSTALLTYPE_DEFAULT.
eInstallType
This parameter specifies the type of installation to patch. A value of 1 for INSTALLTYPE_NETWORK_IMAGE sets this for a administrative installation. The eInstallType parameter is ignored if szInstallPackage is omitted.
Type of installation | Meaning
INSTALLTYPE_NETWORK_IMAGE | Indicates a administrative installation. In this case, szInstallPackage must be set to a package path.
INSTALLTYPE_DEFAULT | Searches system for products to patch. In this case, szInstallPackage must be 0.

szCommandLine
Specifies command line property settings. See About Properties.

Return Values

Value | Meaning
ERROR_SUCCESS | The function completed successfully.
ERROR_PATCH_PACKAGE* | These errors may indicate an error with the patch package.
An error relating to an action | See Error Codes.
Any Initialization Error | An error relating to initialization occurred.

Remarks

Because the list delimiter for transforms, sources and patches is a semicolon, this character should not be used for filenames or paths.

Requirements

Windows NT/2000: Requires Windows NT 4.0 SP3 or later. Available as a redistributable.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in Msi.h.
Library: Use Msi.lib.
Unicode: Implemented as Unicode and ANSI versions on all platforms.

See Also

Error Codes, Initialization Error


MsiCloseAllHandles

The MsiCloseAllHandles function closes all open installation handles allocated by the current thread. This is a diagnostic function and should not be used for cleanup.

UINT MsiCloseAllHandles();

Parameters

This function has no parameters.

Return Values

This function returns 0 if all handles are closed. Otherwise, the function returns the number of handles open prior to its call.

Remarks

MsiCloseAllHandles only closes handles allocated by the calling thread, and does not affect handles allocated by other threads, such as the install handle passed to custom actions.

The MsiOpenPackage function opens a handle to a package and the MsiOpenProduct function opens a handle to a product. These function are for use with functions that access the product database.

Requirements

Windows NT/2000: Requires Windows NT 4.0 SP3 or later. Available as a redistributable.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in Msi.h.
Library: Use Msi.lib.

See Also

Handle Management Functions


MsiCloseHandle

The MsiCloseHandle function closes an open installation handle.

UINT MsiCloseHandle(
  MSIHANDLE hAny    // Installer handle
);

Parameters

hAny
Specifies any open installation handle.

Return Values

Value | Meaning
ERROR_INVALID_HANDLE | An invalid handle was passed to the function.
ERROR_SUCCESS | The function succeeded.

Remarks

MsiCloseHandle must be called from the same thread that requested the creation of the handle.

The following functions supply handles that should be closed after use by calling MsiCloseHandle:

MsiCreateRecord
MsiGetActiveDatabase
MsiGetLastErrorRecord
MsiOpenPackage
MsiOpenProduct
MsiOpenDatabase
MsiDatabaseOpenView
MsiViewFetch
MsiViewGetColumnInfo
MsiDatabaseGetPrimaryKeys
MsiGetSummaryInformation
MsiEnableUIPreview

Note that when writing custom actions, it is recommended to use variables of type PMSIHANDLE because the installer closes PMSIHANDLE objects as they go out of scope, whereas you must close MSIHANDLE objects by calling MsiCloseHandle.

For example, if you use code like this:

MSIHANDLE hRec = MsiCreateRecord(3);

Change it to:

PMSIHANDLE hRec = MsiCreateRecord(3);

Requirements

Windows NT/2000: Requires Windows NT 4.0 SP3 or later. Available as a redistributable.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in Msi.h.
Library: Use Msi.lib.

See Also

Handle Management Functions


MsiCollectUserInfo

The MsiCollectUserInfo function obtains and stores the user information and product ID from an installation wizard.

UINT MsiCollectUserInfo(
  LPCTSTR szProduct    // product code
);

Parameters

szProduct
[in] Specifies the product code of the product for which the user information is collected.

Return Values

Value | Meaning
ERROR_INVALID_PARAMETER | An invalid parameter was passed to the function.
ERROR_SUCCESS | The function succeeded.
An error relating to an action | See Error Codes.
Any Initialization Error | An error relating to initialization occurred.

Remarks

The MsiCollectUserInfo function is typically called by an application during the first run of the application. The application first calls MsiGetUserInfo. If that call fails, the application calls MsiCollectUserInfo. MsiCollectUserInfo opens the product's installation package and invokes a wizard sequence that collects user information. Upon completion of the sequence, user information is registered. Since this API requires an authored user interface, the user interface level should be set to full by calling MsiSetInternalUI as INSTALLUILEVEL_FULL.

The MsiCollectUserInfo invokes a FirstRun Dialog.

Requirements

Windows NT/2000: Requires Windows NT 4.0 SP3 or later. Available as a redistributable.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in Msi.h.
Library: Use Msi.lib.
Unicode: Implemented as Unicode and ANSI versions on all platforms.

See Also

Application-Only Functions, Error Codes, Initialization Error


MsiConfigureFeature

The MsiConfigureFeature function configures the installed state for a product feature.

UINT MsiConfigureFeature(
  LPCTSTR szProduct,          // product code
  LPCTSTR szFeature,          // feature ID
  INSTALLSTATE eInstallState  // install state
);

Parameters

szProduct
[in] Specifies the product code for the product to be configured.
szFeature
[in] Specifies the feature ID for the feature to be configured.
eInstallState
[in] Specifies the installation state for the feature. This parameter must be one of the following values.
Value | Meaning
INSTALLSTATE_ADVERTISED | The feature is advertised
INSTALLSTATE_LOCAL | The feature is installed locally.
INSTALLSTATE_ABSENT | The feature is uninstalled.
INSTALLSTATE_SOURCE | The feature is installed to run from source.
INSTALLSTATE_DEFAULT | The feature is installed to its default location.

Return Values

Value | Meaning
ERROR_INVALID_PARAMETER | An invalid parameter was passed to the function.
ERROR_SUCCESS | The function succeeded.
An error relating to an action | See Error Codes.
Any Initialization Error | An error relating to initialization occurred.

Requirements

Windows NT/2000: Requires Windows NT 4.0 SP3 or later. Available as a redistributable.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in Msi.h.
Library: Use Msi.lib.
Unicode: Implemented as Unicode and ANSI versions on all platforms.

See Also

Installation and Configuration Functions, Error Codes, Initialization Error, Displayed Error Messages


MsiConfigureProduct

The MsiConfigureProduct function installs or uninstalls a product.

UINT MsiConfigureProduct(
  LPCTSTR szProduct,            // product code
  int iInstallLevel,            // install level
  INSTALLSTATE eInstallState    // install state
);

Parameters

szProduct
[in] Specifies the product code for the product to be configured.
iInstallLevel
[in] Specifies how much of the product should be installed when installing the product to its default state. The iInstallLevel parameter will be ignored, and all features will be installed, if the eInstallState parameter is set to any other value than INSTALLSTATE_DEFAULT.

This parameter can be one of the following values.
Value | Meaning
INSTALLLEVEL_DEFAULT | The authored default features are installed.
INSTALLLEVEL_MINIMUM | Only the required features are installed. You can specify a value between INSTALLLEVEL_MINIMUM and INSTALLLEVEL_MAXIMUM to install a subset of available features.
INSTALLLEVEL_MAXIMUM | All features are installed. You can specify a value between INSTALLLEVEL_MINIMUM and INSTALLLEVEL_MAXIMUM to install a subset of available features.

eInstallState
[in] Specifies the installation state for the product. This parameter can be one of the following values.
Value | Meaning
INSTALLSTATE_LOCAL | The product is to be installed with all features installed locally.
INSTALLSTATE_ABSENT | The product is uninstalled.
INSTALLSTATE_SOURCE | The product is to be installed with all features installed to run from source.
INSTALLSTATE_DEFAULT | The product is to be installed with all features installed to the default states specified in the Feature table.
INSTALLSTATE_ADVERTISED | The product is advertised.

Return Values

Value | Meaning
ERROR_INVALID_PARAMETER | An invalid parameter was passed to the function.
ERROR_SUCCESS | The function succeeded.
An error relating to an action | See Error Codes.
Any Initialization Error | An error relating to initialization occurred.

Remarks

The MsiConfigureProduct function displays the user interface using the current settings. User interface settings can be changed with MsiSetInternalUI and MsiSetExternalUI.

The iInstallLevel parameter will be ignored, and all features of the product will be installed, if the eInstallState parameter is set to any other value than INSTALLSTATE_DEFAULT. To control the installation of individual features when the eInstallState parameter is not set to INSTALLSTATE_DEFAULT use MsiConfigureFeature.

Requirements

Windows NT/2000: Requires Windows NT 4.0 SP3 or later. Available as a redistributable.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in Msi.h.
Library: Use Msi.lib.
Unicode: Implemented as Unicode and ANSI versions on all platforms.

See Also

Installation and Configuration Functions, Error Codes, Initialization Error, Displayed Error Messages


MsiConfigureProductEx

The MsiConfigureProductEx function installs or uninstalls a product. A product command line may also be specified.

UINT MsiConfigureProductEx(
  LPCTSTR szProduct,            // product code
  int iInstallLevel,            // install level
  INSTALLSTATE eInstallState,   // install state
  LPCTSTR szCommandLine         // product command line
);

Parameters

szProduct
[in] Specifies the product code for the product to be configured.
iInstallLevel
[in] Specifies how much of the product should be installed when installing the product to its default state. The iInstallLevel parameter are ignored, and all features are installed, if the eInstallState parameter is set to any other value than INSTALLSTATE_DEFAULT.

This parameter can be one of the following values.
Value | Meaning
INSTALLLEVEL_DEFAULT | The authored default features are installed.
INSTALLLEVEL_MINIMUM | Only the required features are installed. You can specify a value between INSTALLLEVEL_MINIMUM and INSTALLLEVEL_MAXIMUM to install a subset of available features.
INSTALLLEVEL_MAXIMUM | All features are installed. You can specify a value between INSTALLLEVEL_MINIMUM and INSTALLLEVEL_MAXIMUM to install a subset of available features.

eInstallState
[in] Specifies the installation state for the product. This parameter can be one of the following values.
Value | Meaning
INSTALLSTATE_LOCAL | The product is to be installed with all features installed locally.
INSTALLSTATE_ABSENT | The product is uninstalled.
INSTALLSTATE_SOURCE | The product is to be installed with all features installed to run from source.
INSTALLSTATE_DEFAULT | The product is to be installed with all features installed to the default states specified in the Feature table.
INSTALLSTATE_ADVERTISED | The product is advertised.

szCommandLine
[in] Specifies the command line property settings. This should be a list of the format Property=Setting Property=Setting. See About Properties.

Return Values

Value | Meaning
ERROR_INVALID_PARAMETER | An invalid parameter was passed to the function.
ERROR_SUCCESS | The function succeeded.
An error relating to an action | See Error Codes.
Any Initialization Error | An error relating to initialization occurred.

Remarks

The command line passed in as szCommandLine can contain any of the Feature Installation Options Properties. In this case, the eInstallState passed must be INSTALLSTATE_DEFAULT.

The iInstallLevel parameter is ignored and all features of the product are installed if the eInstallState parameter is set to any other value than INSTALLSTATE_DEFAULT. To control the installation of individual features when the eInstallState parameter is not set to INSTALLSTATE_DEFAULT use MsiConfigureFeature.

The MsiConfigureProductEx function displays the user interface using the current settings. User interface settings can be changed with MsiSetInternalUI and MsiSetExternalUI.

Requirements

Windows NT/2000: Requires Windows NT 4.0 SP3 or later. Available as a redistributable.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in Msi.h.
Library: Use Msi.lib.
Unicode: Implemented as Unicode and ANSI versions on all platforms.

See Also

Installation and Configuration Functions, Error Codes, Initialization Error, Displayed Error Messages


MsiEnableLog

The MsiEnableLog function sets the log mode for all installations that are initiated in the calling process.

UINT MsiEnableLog(
  DWORD dwLogMode,      // flags designating operations to report
  LPCTSTR szLogFile,    // log file or NULL for external handler
  DWORD dwLogAttributes // INSTALLLOGATTRIBUTES flags
);

Parameters

dwLogMode
[in] Specifies the log mode. This parameter can be one or more of the following values.
Value | Meaning
INSTALLLOGMODE_FATALEXIT | Logs out of memory or fatal exit information.
INSTALLLOGMODE_ERROR | Logs the error messages.
INSTALLLOGMODE_WARNING | Logs the warning messages.
INSTALLLOGMODE_USER | Logs the user requests.
INSTALLLOGMODE_INFO | Logs the status messages that are not displayed.
INSTALLLOGMODE_RESOLVESOURCE | Request to determine a valid source location.
INSTALLLOGMODE_OUTOFDISKSPACE | Indicates insufficient disk space.
INSTALLLOGMODE_ACTIONSTART | Logs the start of new installation actions.
INSTALLLOGMODE_ACTIONDATA | Logs the data record with the installation action.
INSTALLLOGMODE_COMMONDATA | Logs the parameters for user-interface initialization.
INSTALLLOGMODE_PROPERTYDUMP | Logs the property values at termination.
INSTALLLOGMODE_VERBOSE | Sends large amounts of information to log file not generally useful to users. May be used for support.

szLogFile
[in] Specifies the string that holds the full path to the log file. Entering a Null disables logging, in which case dwlogmode is ignored. If a path is supplied, then dwlogmode must not be zero.
dwLogAttributes
[in] Specifies how frequently the log buffer is to be flushed.
Value | Meaning
INSTALLLOGATTRIBUTES_APPEND | Forces the log buffer to be flushed after every 20 log lines.
INSTALLLOGATTRIBUTES_FLUSHEACHLINE | Forces the log buffer to be flushed after each line.

Return Values

Value | Meaning
ERROR_INVALID_PARAMETER | An invalid log mode was specified.
ERROR_SUCCESS | The function succeeded.

Remarks

For a description of the Logging policy, see System Policy.

Requirements

Windows NT/2000: Requires Windows NT 4.0 SP3 or later. Available as a redistributable.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in Msi.h.
Library: Use Msi.lib.
Unicode: Implemented as Unicode and ANSI versions on all platforms.

See Also

Interface and Logging Functions, Logging


MsiEnumClients

The MsiEnumClients function enumerates the clients for a given installed component. The function retrieves one product code each time it is called.

UINT MsiEnumClients(
  LPCTSTR szComponent, // component code, string GUID
  DWORD iProductIndex, // 0-based index into client products
  LPTSTR lpProductBuf  // buffer to receive GUID
);

Parameters

szComponent
[in] Specifies the component whose clients are to be enumerated.
iProductIndex
[in] Specifies the index of the client to retrieve. This parameter should be zero for the first call to the MsiEnumClients function and then incremented for subsequent calls. Because clients are not ordered, any new client has an arbitrary index. This means that the function can return clients in any order.
lpProductBuf
[out] Pointer to a buffer that receives the product code. This buffer must be 39 characters long. The first 38 characters are for the GUID, and the last character is for the terminating NULL character.

Return Values

Value | Meaning
ERROR_BAD_CONFIGURATION | The configuration data is corrupt.
ERROR_INVALID_PARAMETER | An invalid parameter was passed to the function.
ERROR_NO_MORE_ITEMS | There are no clients to return.
ERROR_SUCCESS | A value was enumerated.
ERROR_UNKNOWN_COMPONENT | The specified component is unknown.

Remarks

To enumerate clients, an application should initially call the MsiEnumClients function with the iProductIndex parameter set to zero. The application should then increment the iProductIndex parameter and call MsiEnumClients until there are no more clients (that is, until the function returns ERROR_NO_MORE_ITEMS).

Requirements

Windows NT/2000: Requires Windows NT 4.0 SP3 or later. Available as a redistributable.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in Msi.h.
Library: Use Msi.lib.
Unicode: Implemented as Unicode and ANSI versions on all platforms.

See Also

System Status Functions


MsiEnumComponentQualifiers

The MsiEnumComponentQualifiers function enumerates the advertised qualifiers for the given component. This function retrieves one qualifier each time it is called.

UINT MsiEnumComponentQualifiers(
  LPTSTR szComponent,           // component ID
  DWORD iIndex,                 // 0-based index into component qualifiers
  LPTSTR lpQualifierBuf,        // buffer to return qualifier
  DWORD *pcchQualifierBuf,      // qualifier buffer character count
  LPTSTR lpApplicationDataBuf,  // buffer to return application-registered data
  DWORD *pcchApplicationDataBuf // lpApplicationDataBuf character count
);

Parameters

szComponent
[in] Specifies component whose qualifiers are to be enumerated.
iIndex
[in] Specifies the index of the qualifier to retrieve. This parameter should be zero for the first call to the MsiEnumComponentQualifiers function and then incremented for subsequent calls. Because qualifiers are not ordered, any new qualifier has an arbitrary index. This means that the function can return qualifiers in any order.
lpQualifierBuf
[out] Pointer to a buffer that receives the qualifier code.
pcchQualifierBuf
[in] [out] Pointer to a variable that specifies the size, in characters, of the buffer pointed to by the lpQualifierBuf parameter. On input this size should include the terminating NULL character. On return, the value does not include the NULL character.
lpApplicationDataBuf
[out] Pointer to a buffer that receives the application registered data for the qualifier. This parameter can be NULL.
pcchApplicationDataBuf
[in] [out] Pointer to a variable that specifies the size, in characters, of the buffer pointed to by the lpApplicationDataBuf parameter. On input this size should include the terminating NULL character. On return, the value does not include the NULL character. This parameter can be NULL only if the lpApplicationDataBuf parameter is NULL.

Return Values

Value | Meaning
ERROR_BAD_CONFIGURATION | The configuration data is corrupt.
ERROR_INVALID_PARAMETER | An invalid parameter was passed to the function.
ERROR_MORE_DATA | A buffer is to small to hold the requested data.
ERROR_NO_MORE_ITEMS | There are no qualifiers to return.
ERROR_SUCCESS | A value was enumerated.
ERROR_UNKNOWN_COMPONENT | The specified component is unknown.

Remarks

To enumerate qualifiers, an application should initially call the MsiEnumComponentQualifiers function with the iIndex parameter set to zero. The application should then increment the iIndex parameter and call MsiEnumComponentQualifiers until there are no more qualifiers (that is, until the function returns ERROR_NO_MORE_ITEMS).

When MsiEnumComponentQualifiers returns, the pcchQualifierBuf parameter contains the length of the qualifier string stored in the buffer. The count returned does not include the terminating null character. If the buffer is not big enough, MsiEnumComponentQualifiers returns ERROR_MORE_DATA, and this parameter contains the size of the string, in characters, without counting the NULL character. The same mechanism applies to pcchDescriptionBuf.

Requirements

Windows NT/2000: Requires Windows NT 4.0 SP3 or later. Available as a redistributable.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in Msi.h.
Library: Use Msi.lib.
Unicode: Implemented as Unicode and ANSI versions on all platforms.

See Also

System Status Functions


MsiEnumComponents

The MsiEnumComponents function enumerates the installed components for all products. This function retrieves one component code each time it is called.

UINT MsiEnumComponents(
  DWORD iComponentIndex, // 0-based index into installed components
  LPTSTR lpComponentBuf  // buffer of char count: 39
                         // (size of string GUID)
);

Parameters

iComponentIndex
[in] Specifies the index of the component to retrieve. This parameter should be zero for the first call to the MsiEnumComponents function and then incremented for subsequent calls. Because components are not ordered, any new component has an arbitrary index. This means that the function can return components in any order.
lpComponentBuf
[out] Pointer to a buffer that receives the component code.

Return Values

Value | Meaning
ERROR_BAD_CONFIGURATION | The configuration data is corrupt.
ERROR_INVALID_PARAMETER | An invalid parameter was passed to the function.
ERROR_NO_MORE_ITEMS | There are no components to return.
ERROR_SUCCESS | A value was enumerated.

Remarks

To enumerate components, an application should initially call the MsiEnumComponents function with the iComponentIndex parameter set to zero. The application should then increment the iComponentIndex parameter and call MsiEnumComponents until there are no more components (that is, until the function returns ERROR_NO_MORE_ITEMS).

Requirements

Windows NT/2000: Requires Windows NT 4.0 SP3 or later. Available as a redistributable.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in Msi.h.
Library: Use Msi.lib.
Unicode: Implemented as Unicode and ANSI versions on all platforms.

See Also

System Status Functions


MsiEnumFeatures

The MsiEnumFeatures function enumerates the published features for a given product. This function retrieves one feature ID each time it is called.

UINT MsiEnumFeatures(
  LPCTSTR szProduct,     // product code, string GUID
  DWORD iFeatureIndex,   // 0-based index into published features
  LPTSTR lpFeatureBuf,   // buffer for feature
  LPTSTR lpParentBuf     // buffer for parent of feature
);

Parameters

szProduct
[in] Specifies the product whose features are to be enumerated.
iFeatureIndex
[in] Specifies the index of the feature to retrieve. This parameter should be zero for the first call to the MsiEnumFeatures function and then incremented for subsequent calls. Because features are not ordered, any new feature has an arbitrary index. This means that the function can return features in any order.
lpFeatureBuf
[out] Pointer to a buffer that receives the feature ID. Must be sized to hold a string of length MAX_FEATURE_CHARS.
lpParentBuf
[out] Pointer to a buffer that receives the feature ID of the parent of the feature. Must be sized to hold a string of length MAX_FEATURE_CHARS. This parameter can be null.

Return Values

Value | Meaning
ERROR_BAD_CONFIGURATION | The configuration data is corrupt.
ERROR_INVALID_PARAMETER | An invalid parameter was passed to the function.
ERROR_NO_MORE_ITEMS | There are no features to return.
ERROR_SUCCESS | A value was enumerated.
ERROR_UNKNOWN_PRODUCT | The specified product is unknown.

Remarks

To enumerate features, an application should initially call the MsiEnumFeatures function with the iFeatureIndex parameter set to zero. The application should then increment the iFeatureIndex parameter and call MsiEnumFeatures until there are no more features (that is, until the function returns ERROR_NO_MORE_ITEMS).

Requirements

Windows NT/2000: Requires Windows NT 4.0 SP3 or later. Available as a redistributable.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in Msi.h.
Library: Use Msi.lib.
Unicode: Implemented as Unicode and ANSI versions on all platforms.

See Also

System Status Functions


MsiEnumPatches

The MsiEnumPatches function enumerates all of the patches that have been applied to a product. The function returns the patch code GUID for each patch that has been applied to the product and returns a list of transforms from each patch that apply to the product. Note that patches may have many transforms only some of which are applicable to a particular product. The list of transforms are returned in the same format as the value of the TRANSFORMS property.

NOTE: pcchTransformsBuf is not set to the number of characters copied to lpTransformsBuf upon a successful return of MsiEnumPatches.

UINT MsiEnumPatches(
  LPCTSTR szProduct,       // product code, string GUID
  DWORD iPatchIndex,       // 0-based index into patches
  LPTSTR lpPatchBuf,       // buffer for patch
  LPTSTR lpTransformsBuf,  // buffer for transforms
  DWORD *pcchTransformsBuf // transforms buffer character count
);

Parameters

szProduct
[in] Specifies the product for which patches are to be enumerated.
iPatchIndex
[in] Specifies the index of the patch to retrieve. This parameter should be zero for the first call to the MsiEnumPatches function and then incremented for subsequent calls.
lpPatchBuf
[out] Pointer to a buffer that receives the patch's GUID. This argument is required.
lpTransformsBuf
[out] Pointer to a buffer that receives the list of transforms in the patch that are applicable to the product. This argument is required and cannot be Null.
pcchTransformsBuf
[in] [out] Set to the number of characters copied to lpTransformsBuf upon an unsuccessful return of the function. Not set for a successful return. The count does not include the terminating null.

Return Values

Value | Meaning
ERROR_BAD_CONFIGURATION | The configuration data is corrupt.
ERROR_INVALID_PARAMETER | An invalid parameter was passed to the function.
ERROR_NO_MORE_ITEMS | There are no patches to return.
ERROR_SUCCESS | A value was enumerated.
ERROR_MORE_DATA | A buffer is too small to hold the requested data.

Remarks

To enumerate patches, an application should initially call the MsiEnumPatches function with the iPatchIndex parameter set to zero. The application should then increment the iPatchIndex parameter and call MsiEnumPatches until there are no more products (until the function returns ERROR_NO_MORE_ITEMS).

If the buffer is too small to hold the requested data, MsiEnumPatches returns ERROR_MORE_DATA and pcchTransformsBuf contains the number of characters copied to lpTransformsBuf, without counting the Null character.

Requirements

Windows NT/2000: Requires Windows NT 4.0 SP3 or later. Available as a redistributable.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in Msi.h.
Library: Use Msi.lib.
Unicode: Implemented as Unicode and ANSI versions on all platforms.


MsiEnumProducts

The MsiEnumProducts function enumerates through all the products currently advertised or installed. Both per-user and per-machine installations and advertisements are enumerated.

UINT MsiEnumProducts(
  DWORD iProductIndex, // 0-based index into registered products
  LPTSTR lpProductBuf  // buffer to receive GUID
);

Parameters

iProductIndex
[in] Specifies the index of the product to retrieve. This parameter should be zero for the first call to the MsiEnumProducts function and then incremented for subsequent calls. Because products are not ordered, any new product has an arbitrary index. This means that the function can return products in any order.
lpProductBuf
[out] Pointer to a buffer that receives the product code. This buffer must be 39 characters long. The first 38 characters are for the GUID, and the last character is for the terminating NULL character.

Return Values

Value | Meaning
ERROR_BAD_CONFIGURATION | The configuration data is corrupt.
ERROR_INVALID_PARAMETER | An invalid parameter was passed to the function.
ERROR_NO_MORE_ITEMS | There are no products to return.
ERROR_SUCCESS | A value was enumerated.

Remarks

To enumerate products, an application should initially call the MsiEnumProducts function with the iProductIndex parameter set to zero. The application should then increment the iProductIndex parameter and call MsiEnumProducts until there are no more products (until the function returns ERROR_NO_MORE_ITEMS).

Requirements

Windows NT/2000: Requires Windows NT 4.0 SP3 or later. Available as a redistributable.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in Msi.h.
Library: Use Msi.lib.
Unicode: Implemented as Unicode and ANSI versions on all platforms.

See Also

System Status Functions


MsiEnumRelatedProducts

The MsiEnumProducts function enumerates products with a specified upgrade code. This function lists the currently installed and advertised products that have the specified UpgradeCode property in their Property table.

UINT MsiEnumRelatedProducts(
  LPCTSTR lpUpgradeCode  // upgrade code of products to enumerate
  DWORD dwReserved,      // reserved, must be 0
  DWORD iProductIndex,   // 0-based index into registered products
  LPTSTR lpProductBuf    // buffer of character count 39 to receive GUID
);

Parameters

lpUpgradeCode
[in] The upgrade code of related products that the installer is to enumerate.
dwReserved
[in] This parameter is reserved and must be 0.
iProductIndex
[in] The 0-based index into the registered products.
lpProductBuf
[out] A buffer of character count 39 to receive the product code GUID.

Return Values

Value | Meaning
ERROR_BAD_CONFIGURATION | The configuration data is corrupt.
ERROR_INVALID_PARAMETER | An invalid parameter was passed to the function.
ERROR_NO_MORE_ITEMS | There are no products to return.
ERROR_SUCCESS | A value was enumerated.

Remarks

See UpgradeCode property.

To enumerate currently installed and advertised products that have a specific upgrade code, an application should initially call the MsiEnumRelatedProducts function with the iProductIndex parameter set to zero. The application should then increment the iProductIndex parameter and call MsiEnumRelatedProducts until the function returns ERROR_NO_MORE_ITEMS, which means there are no more products with the specified upgrade code.

This function is not available with Windows Installer version 1.0.

Requirements

Windows NT/2000: Requires Windows NT 4.0 SP3 or later. Available as a redistributable.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in Msi.h.
Library: Use Msi.lib.
Unicode: Implemented as Unicode and ANSI versions on all platforms.


MsiGetComponentPath

The MsiGetComponentPath function returns the full path to an installed component. If the key path for the component is a registry key then the registry key is returned.

INSTALLSTATE MsiGetComponentPath(
  LPCTSTR szProduct,   // product code for client product
  LPCTSTR szComponent, // component ID
  LPTSTR lpPathBuf,    // returned path
  DWORD *pcchBuf       // buffer character count
);

Parameters

szProduct
[in] Specifies the product code for the client product.
szComponent
[in] Specifies the component ID of the component to be located.
lpPathBuf
[out] Pointer to a variable that receives the path to the component. This parameter can be NULL. If the component is a registry key, the registry roots are represented numerically. If this is a registry subkey path, there is a backslash at the end of the Key Path. If this is a registry value key path, there is no backslash at the end. For example, a registry path of "HKEY_CURRENT_USER\SOFTWARE\Microsoft" would be returned as "01:\SOFTWARE\Microsoft\". The registry roots returned are defined as follows:
Root | Returned value
HKEY_CLASSES_ROOT | 00
HKEY_CURRENT_USER | 01
HKEY_LOCAL_MACHINE | 02
HKEY_USERS | 03

pcchBuf
[in] [out] Pointer to a variable that specifies the size, in characters, of the buffer pointed to by the lpPathBuf parameter. The count does not include the terminating null.

If lpPathBuf is NULL, pcchBuf can be NULL.

Return Values

Value | Meaning
INSTALLSTATE_NOTUSED | The component being requested is disabled on the computer.
INSTALLSTATE_ABSENT | The component is not installed.
INSTALLSTATE_BAD_CONFIGURATION | The configuration data is corrupt.
INSTALLSTATE_INVALIDARG | One of the function parameters is invalid.
INSTALLSTATE_LOCAL | The component is installed locally.
INSTALLSTATE_SOURCE | The component is installed to run from source.
INSTALLSTATE_SOURCEABSENT | The component source is inaccessible.
INSTALLSTATE_UNKNOWN | The product code or component ID is unknown.

Remarks

Upon success of the MsiGetComponentPath function, the pcchBuf parameter contains the length of the string in lpPathBuf.

The MsiGetComponentPath function might return INSTALLSTATE_ABSENT or INSTALL_STATE_UNKNOWN, for the following reasons:

  • INSTALLSTATE_ABSENT

    The application did not properly ensure that the feature was installed by calling MsiUseFeature and, if necessary, MsiConfigureFeature.

  • INSTALLSTATE_UNKNOWN

    The feature is not published. The application should have determined this earlier by calling MsiQueryFeatureState or MsiEnumFeatures. The application makes these calls while it initializes. An application should only use features that are known to be published. Since INSTALLSTATE_UNKNOWN should have been returned by MsiUseFeature as well, either MsiUseFeature was not called, or its return value was not properly checked.

Requirements

Windows NT/2000: Requires Windows NT 4.0 SP3 or later. Available as a redistributable.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in Msi.h.
Library: Use Msi.lib.
Unicode: Implemented as Unicode and ANSI versions on all platforms.

See Also

Component-Specific Functions


MsiGetFeatureInfo

The MsiGetFeatureInfo function returns descriptive information for a feature.

UINT MsiGetFeatureInfo(
  MSIHANDLE hProduct,  // product handle obtained from MsiOpenProduct
  LPCTSTR szFeature,   // feature name
  DWORD *lpAttributes, // attribute flags
  LPTSTR lpTitleBuf,   // localized name
  DWORD *pcchTitleBuf, // buffer character count
  LPTSTR lpHelpBuf,    // description
  DWORD *pcchHelpBuf   // buffer character count
);

Parameters

hProduct
[in] Handle to the product that owns the feature. This handle is obtained from MsiOpenProduct.
szFeature
[in] Specifies the feature code for the feature about which information should be returned.
lpAttributes
[in] Specifies the attribute flags. Must be one or more of the following.
Flag | Returned value
INSTALLFEATUREATTRIBUTE_FAVORLOCAL | 1
INSTALLFEATUREATTRIBUTE_FAVORSOURCE | 2
INSTALLFEATUREATTRIBUTE_FOLLOWPARENT | 4
INSTALLFEATUREATTRIBUTE_FAVORADVERTISE | 8
INSTALLFEATUREATTRIBUTE_DISALLOWADVERTISE | 16
INSTALLFEATUREATTRIBUTE_NOUNSUPPORTEDADVERTISE | 32

For information on how these flags work together, see the Feature table. Note however that the values returned by MsiGetFeatureInfo are double the values in the Attributes column of the Feature Table.

lpTitleBuf
[out] Pointer to a buffer to receive the localized descriptive name of the feature.
pcchTitleBuf
[in] [out] As input, the size of lpTitleBuf. As output, the number of characters returned in lpTitleBuf. The count does not include the terminating null.
lpHelpBuf
[out] Pointer to a buffer to receive the localized descriptive name of the feature.
pcchHelpBuf
[in] [out] As input, the size of lpHelpBuf. As output, the number of characters returned in lpHelpBuf. The count does not include the terminating null.

Return Values

Value | Meaning
ERROR_INVALID_HANDLE | The product handle is invalid.
ERROR_INVALID_PARAMETER | One of the parameters is invalid.
ERROR_MORE_DATA | A buffer is too small to hold the requested data.
ERROR_SUCCESS | The function returned successfully.
ERROR_UNKNOWN_FEATURE | The feature is not known.

Remarks

The buffer sizes for the MsiGetFeatureInfo function should include an extra character for the terminating NULL character upon input. If a buffer is too small, the returned string will be truncated with NULL, and the buffer size will contain the number of characters in the whole string, not including the terminating NULL. For more information, see Calling Database Functions From Programs.

Requirements

Windows NT/2000: Requires Windows NT 4.0 SP3 or later. Available as a redistributable.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in Msi.h.
Library: Use Msi.lib.
Unicode: Implemented as Unicode and ANSI versions on all platforms.

See Also

Product Query Functions


MsiGetFeatureUsage

The MsiGetFeatureUsage returns the usage metrics for a product feature.

UINT MsiGetFeatureUsage(
  LPCTSTR szProduct,    // product code
  LPCTSTR szFeature,    // feature ID
  DWORD *pdwUseCount,   // returned use count
  WORD *pwDateUsed      // last date used
);

Parameters

szProduct
[in] Specifies the product code for the product containing the feature.
szFeature
[in] Specifies the feature code for the feature for which metrics are to be returned.
pdwUseCount
[out] Indicates the number of times the feature has been used.
pwDateUsed
[out] Specifies the date that the feature was last used. The date is in the MS-DOS date format, as shown in the following table.
Bits | Contents
0 – 4 | Day of the month (1-31)
5 – 8 | Month (1 = January, 2 = February, and so on)
9 – 15 | Year offset from 1980 (add 1980 to get actual year)

Return Values

Valkue | Meaning
ERROR_BAD_CONFIGURATION | The configuration data is corrupt.
ERROR_INSTALL_FAILURE | No usage information is available or the product or feature is invalid.
ERROR_SUCCESS | The function completed successfully.

Requirements

Windows NT/2000: Requires Windows NT 4.0 SP3 or later. Available as a redistributable.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in Msi.h.
Library: Use Msi.lib.
Unicode: Implemented as Unicode and ANSI versions on all platforms.

See Also

System Status Functions


MsiGetFileHash

The MsiGetFileHash function takes the path to a file and returns a 128-bit hash of that file. Authoring tools may use MsiGetFileHash to obtain the file hash needed to populate the MsiFileHash table.

The Windows Installer uses file hashing as a means to detect and eliminate unnecessary file copying. A file hash stored in the MsiFileHash table may be compared to a hash of an existing file on the user's computer.

UINT MsiGetFileHash(
  LPCTSTR szFilePath,         // path to file
  DWORD dwOptions,            // options — must be 0
  PMSIFILEHASHINFO pHash      // returned file hash info
);

Parameters

szFilePath
[in] Path to file that is to be hashed.
dwOptions
[in] The value in this column must be 0. This parameter is reserved for future use.
pHash
[out] Pointer to the returned file hash information.

Return Values

Value | Meaning
ERROR_SUCCESS | Successful completion.
ERROR_FILE_NOT_FOUND | File does not exist.
ERROR_ACCESS_DENIED | File could not be opened to get version information.
E_FAIL | Unexpected error.

Remarks

The entire 128-bit file hash is returned as four 32-bit fields. The numbering of the four fields is 1-based. The values returned by MsiGetFileHash correspond to the four fields of the MSIFILEHASHINFO structure. The first field corresponds to the HashPart1 column of the MsiFileHash table, the second field corresponds to the HashPart2 column, the third field corresponds to the HashPart3 column, and the fourth field corresponds to the HashPart4 column.

The hash information entered into the MsiFileHash table must be obtained by calling MsiGetFileHash or the FileHash method. Do not attempt to use other methods to generate the file hash.

Requirements

Windows NT/2000: Requires Windows NT 4.0 SP3 or later. Available as a redistributable.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in Msi.h.
Library: Use Msi.lib.
Unicode: Implemented as Unicode and ANSI versions on all platforms.

See Also

MsiFileHash table, MSIFILEHASHINFO, Default File Versioning.


MsiGetFileSignatureInformation

The MsiGetFileSignatureInformation function takes the path to a file that has been digitally signed and returns the file's signer certificate and hash. MsiGetFileSignatureInformation may be called to obtain the signer certificate and hash needed to populate the MsiDigitalCertificate table and MsiDigitalSignature table.

MsiGetFileSignatureInformation is available with Windows Installer version 1.5 and later. Windows Installer version 1.5 only verifies the digital signatures of external cabinets, and only by the use of the MsiDigitalSignature and MsiDigitalCertificate tables.

Windows Installer version 1.5 uses digital signatures as a means to detect corrupted resources. A signer certificate may be compared to the signer certificate of an external resource to be installed by the package.

HRESULT MsiGetFileSignatureInformation(
  LPCTSTR szSignedObjectPath,     // path to signed object
  DWORD dwFlags,                  // extra error case flags
  PCCERT_CONTEXT *ppcCertContext, // returned signer certificate context
  BYTE *pbHashData,               // returned hash buffer, NULL if not desired
  DWORD *pcbHashData              // in/out buffer byte count
);

Parameters

szSignedObjectPath
[in] Path to the file that contains the digital signature.
dwFlags
[in] Special error case flags.
Flag Value Description
MSI_INVALID_HASH_IS_FATAL 0x1 Without this flag set, and when requesting only the certificate context, an invalid hash in the digital signature does not cause MsiGetFileSignatureInformation to return a fatal error.

To return a fatal error for an invalid hash, set the MSI_INVALID_HASH_IS_FATAL flag.

ppcCertContext
[out] Returned signer certificate context
pbHashData
[out] Returned hash buffer. This parameter is optional and can be NULL.
pcbHashData
[in,out] Pointer to a variable that specifies the size, in bytes, of the buffer pointed to by the pbHashData parameter. If pbHashData is NULL, pcbHashData can be NULL.

Return Values

Value | Meaning
ERROR_SUCCESS/S_OK | Successful completion.
ERROR_INVALID_PARAMETER | Invalid parameter was specified.
ERROR_FUNCTION_FAILED | WinVerifyTrust is not available on the system. MsiGetFileSignatureInformation requires the presence of the Wintrust.dll file on the system.
TRUST_E_NO_SIGNATURE | File is not signed
TRUST_E_BAD_DIGEST | The file's current hash is invalid according to the hash stored in the file's digital signature.
CERT_E_REVOKED | The file's signer certificate has been revoked. The file's digital signature is compromised.
TRUST_E_SUBJECT_NOT_TRUSTED | The subject failed the specified verification action. Most trust providers return a more detailed error code that describes the reason for the failure.
TRUST_E_PROVIDER_UNKNOWN | The trust provider is not recognized on this system.
TRUST_E_ACTION_UNKNOWN | The trust provider does not support the specified action.
TRUST_E_SUBJECT_FORM_UNKNOWN | The trust provider does not support the form specified for the subject.

MsiGetFileSignatureInformation also returns all the Win32 error values mapped to their equivalent HRESULT data type by HRESULT_FROM_WIN32.

Remarks

When requesting only the certificate context, an invalid hash in the digital signature does not cause MsiGetFileSignatureInformation to return a fatal error. To return a fatal error for an invalid hash, set the MSI_INVALID_HASH_IS_FATAL flag in the dwFlags parameter.

The certificate context and hash information is extracted from the file by a call to WinVerifyTrust. The ppcCertContext parameter is a duplicate of the signer certificate context from the signature. It is the responsibility of the caller to call CertFreeCertificateContext to free the certificate context when finished.

Note that MsiGetFileSignatureInformation requires the presence of the Wintrust.dll file on the system.

Requirements

Windows NT/2000: Requires Windows NT 4.0 SP3 or later. Available as a redistributable.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in Msi.h.
Library: Use Msi.lib.
Unicode: Implemented as Unicode and ANSI versions on all platforms.

See Also

MsiDigitalCertificate table, MsiDigitalSignature table, Digital Signatures and Windows Installer


MsiGetFileVersion

The MsiGetFileVersion returns the version string and language string in the format that the installer expects to find them in the database. If you just want version information, set lpLangBuf and pcchLangBuf to zero. If you just want language information, set lpVersionBuf and pcchVersionBuf to zero.

UINT MsiGetFileVersion(
  LPCTSTR szFilePath,      // path to the file
  LPCTSTR lpVersionBuf,    // returned version string
  DWORD *pcchVersionBuf,   // buffer byte count
  LPCTSTR lpLangBuf,       // returned language string
  DWORD *pcchLangBuf       // buffer byte count
);

Parameters

szFilePath
[in] Specifies the path to the file.
lpVersionBuf
[in] [out] Returns the file version. Set to 0 for language information only.
pcchVersionBuf
[in] [out] In and out buffer byte count. Set to 0 for language information only. The count does not include the terminating null.
lpLangBuf
[in] [out]Returns the file language. Set to 0 for version information only.
pcchLangBuf
[in] [out] In and out buffer byte count. Set to 0 for version information only. The count does not include the terminating null.

Return Values

Value | Meaning
ERROR_SUCCESS | Successful completion.
ERROR_FILE_NOT_FOUND | File does not exist.
ERROR_ACCESS_DENIED | File could not be opened to get version information.
ERROR_FILE_INVALID | File does not contain version information.
ERROR_INVALID_DATA | The version information is invalid.
E_FAIL | Unexpected error.

Requirements

Windows NT/2000: Requires Windows NT 4.0 SP3 or later. Available as a redistributable.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in Msi.h.
Library: Use Msi.lib.

See Also

System Status Functions


MsiGetPatchInfo

The MsiGetPatchInfo function returns information about a patch.

UINT MsiGetPatchInfo(
  LPCTSTR szPatch,      // patch code
  LPCTSTR szAttribute,  // attribute name, case-sensitive
  LPTSTR lpValueBuf,    // returned value, NULL if not desired
  DWORD *pcchValueBuf   // buffer character count,
);

Parameters

szPatch
[in] Specifies the patch code for the patch package.
szAttribute
[in] Specifies the attribute to be retrieved.
Attribute | Description
INSTALLPROPERTY_LOCALPACKAGE | Local cached package

lpValueBuf
[out] Pointer to a buffer that receives the property value. This parameter can be NULL.
pcchValueBuf
[in] [out] Pointer to a variable that specifies the size, in characters, of the buffer pointed to by the lpValueBuf parameter. The count does not include the terminating null.

If lpValueBuf is NULL, pcchValueBuf can be NULL.

Return Values

Value | Meaning
ERROR_BAD_CONFIGURATION | The configuration data is corrupt.
ERROR_INVALID_PARAMETER | An invalid parameter was passed to the function.
ERROR_MORE_DATA | A buffer is too small to hold the requested data.
ERROR_SUCCESS | The function completed successfully.
ERROR_UNKNOWN_PRODUCT | The patch package is not installed.
ERROR_UNKNOWN_PROPERTY | The property is unrecognized.

Remarks

When the MsiGetPatchInfo function returns, the pcchValueBuf parameter contains the length of the class string stored in the buffer. The count returned does not include the terminating NULL character.

If the buffer is too small to hold the requested data, MsiGetPatchInfo returns ERROR_MORE_DATA, and pcchValueBuf contains the number of characters copied to lpValueBuf, without counting the NULL character.

This function is not available with version 1.0 of the Windows Installer.

Requirements

Windows NT/2000: Requires Windows NT 4.0 SP3 or later. Available as a redistributable.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in Msi.h.
Library: Use Msi.lib.
Unicode: Implemented as Unicode and ANSI versions on all platforms.


MsiGetProductCode

The MsiGetProductCode function returns the product code of an application by using the component code of an installed or advertised component of the application. During initialization, an application must determine under which product code it has been installed or advertised.

UINT MsiGetProductCode(
  LPCTSTR szComponent,  // component code for application
  LPTSTR lpProductBuf   // buffer to receive GUID
);

Parameters

szComponent
[in] This parameter specifies the component code of a component that has been installed by the application. This will be typically the component code of the component containing the executable file of the application.
lpProductBuf
[out] Pointer to a buffer that receives the product code. This buffer must be 39 characters long. The first 38 characters are for the GUID, and the last character is for the terminating NULL character.

Return Values

Value | Meaning
ERROR_BAD_CONFIGURATION | The configuration data is corrupt.
ERROR_INSTALL_FAILURE | The product code could not be determined.
ERROR_INVALID_PARAMETER | An invalid parameter was passed to the function.
ERROR_SUCCESS | The function completed successfully.
ERROR_UNKNOWN_COMPONENT | The specified component is unknown.

Remarks

During initialization, an application must determine the product code under which it was installed. An application can be part of different products in different installations. For example, an application can be part of a suite of applications, or it can be installed by itself.

Requirements

Windows NT/2000: Requires Windows NT 4.0 SP3 or later. Available as a redistributable.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in Msi.h.
Library: Use Msi.lib.
Unicode: Implemented as Unicode and ANSI versions on all platforms.

See Also

Application-Only Functions


MsiGetProductInfo

The MsiGetProductInfo function returns product information for published and installed products.

UINT MsiGetProductInfo(
  LPCTSTR szProduct,   // product code
  LPCTSTR szProperty,  // product property
  LPTSTR lpValueBuf,   // buffer to return property value
  DWORD *pcchValueBuf  // buffer character count
);

Parameters

szProduct
[in] Specifies the product code for the product.
szProperty
[in] Specifies the property to be retrieved. The properties in the following list can only be retrieved from applications that are already installed. Note that required properties are guaranteed to be available, but other properties are available only if that property has been set. See the indicated links to the installer properties for information about how each property is set.
Installed properties | Description
INSTALLPROPERTY_INSTALLEDPRODUCTNAME | Installed product name. See ProductName property.
INSTALLPROPERTY_VERSIONSTRING | Product version. See ProductVersion property.
INSTALLPROPERTY_HELPLINK | Support link. See ARPHELPLINK property.
INSTALLPROPERTY_HELPTELEPHONE | Support telephone. See ARPHELPTELEPHONE property.
INSTALLPROPERTY_INSTALLLOCATION | Installation location. See ARPINSTALLLOCATION property.
INSTALLPROPERTY_INSTALLSOURCE | Installation source. See SourceDir property.
INSTALLPROPERTY_INSTALLDATE | Installation date.
INSTALLPROPERTY_PUBLISHER | Publisher. See Manufacturer property.
INSTALLPROPERTY_LOCALPACKAGE | Local cached package
INSTALLPROPERTY_URLINFOABOUT | URL information. See ARPURLINFOABOUT property.
INSTALLPROPERTY_URLUPDATEINFO | URL update information. See ARPURLUPDATEINFO property.
INSTALLPROPERTY_VERSIONMINOR | Minor product version derived from ProductVersion property.
INSTALLPROPERTY_VERSIONMAJOR | Major product version derived from ProductVersion property.

The properties in the following list can also be retrieved from applications that are advertised.
Advertised properties | Description
INSTALLPROPERTY_TRANSFORMS | Transforms
INSTALLPROPERTY_LANGUAGE | Product language
INSTALLPROPERTY_PRODUCTNAME | Human readable product name. See ProductName property.
INSTALLPROPERTY_ASSIGNMENTTYPE | Assignment type
INSTALLPROPERTY_ADVTFLAGS | Advertisment flags.
INSTALLPROPERTY_PACKAGECODE | Identifier of the package this product was installed from. For details, see Package Codes .
INSTALLPROPERTY_VERSION | Product version derived from ProductVersion property.
INSTALLPROPERTY_PRODUCTICON | Primary Icon for the package. For details, see ARPPRODUCTICON property.
INSTALLPROPERTY_PACKAGENAME | Name of the original installation package.

lpValueBuf
[out] Pointer to a buffer that receives the property value. This parameter can be NULL.
pcchValueBuf
[in] [out]Pointer to a variable that specifies the size, in characters, of the buffer pointed to by the lpValueBuf parameter. The count does not include the terminating null.

If lpValueBuf is NULL, pcchValueBuf can be NULL.

Return Values

Value | Meaning
ERROR_BAD_CONFIGURATION | The configuration data is corrupt.
ERROR_INVALID_PARAMETER | An invalid parameter was passed to the function.
ERROR_MORE_DATA | A buffer is too small to hold the requested data.
ERROR_SUCCESS | The function completed successfully.
ERROR_UNKNOWN_PRODUCT | The product is unadvertised or uninstalled.
ERROR_UNKNOWN_PROPERTY | The property is unrecognized.

Remarks

When the MsiGetProductInfo function returns, the pcchValueBuf parameter contains the length of the class string stored in the buffer. The count returned does not include the terminating NULL character. If the buffer is not big enough, MsiGetProductInfo returns ERROR_MORE_DATA, and MsiGetProductInfo contains the size of the string, in characters, without counting the NULL character.

MsiGetProductInfo(INSTALLPROPERTY_LOCALPACKAGE) does not necessarily return a path to the cached package. The cached package is for internal use only. Maintenance mode installations should be invoked via the MsiConfigureFeature, MsiConfigureProduct, or MsiConfigureProductEx functions.

Requirements

Windows NT/2000: Requires Windows NT 4.0 SP3 or later. Available as a redistributable.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in Msi.h.
Library: Use Msi.lib.
Unicode: Implemented as Unicode and ANSI versions on all platforms.

See Also

System Status Functions


MsiGetProductProperty

The MsiGetProductProperty function retrieves product properties. These properties are in the product database.

UINT MsiGetProductProperty(
  MSIHANDLE hProduct,   // product handle obtained from MsiOpenProduct
  LPCTSTR szProperty,   // property name, case-sensitive
  LPTSTR lpValueBuf,    // returned value, NULL if not desired
  DWORD *pcchValueBuf   // buffer character count
);

Parameters

hProduct
[in] Handle to the product obtained from MsiOpenProduct.
szProperty
[in] Specifies the property to retrieve. This is case-sensitive.
lpValueBuf
[out] Pointer to a buffer that receives the property value. The value is truncated and null-terminated if lpValueBuf is too small. This parameter can be NULL.
pcchValueBuf
[in] [out]Pointer to a variable that specifies the size, in characters, of the buffer pointed to by the lpValueBuf parameter. The count does not include the terminating null.

If lpValueBuf is NULL, pcchValueBuf can be NULL.

Return Values

Value | Meaning
ERROR_INVALID_PARAMETER | An invalid parameter was passed to the function.
ERROR_INVALID_HANDLE | An invalid handle was passed to the function.
ERROR_MORE_DATA | A buffer is too small to hold the entire property value.
ERROR_SUCCESS | The function completed successfully.

Remarks

When the MsiGetProductProperty function returns, the pcchValueBuf parameter contains the length of the class string stored in the buffer. The count returned does not include the terminating NULL character. If the buffer is not big enough, MsiGetProductProperty returns ERROR_MORE_DATA, and MsiGetProductProperty contains the size of the string, in characters, without counting the NULL character.

Requirements

Windows NT/2000: Requires Windows NT 4.0 SP3 or later. Available as a redistributable.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in Msi.h.
Library: Use Msi.lib.
Unicode: Implemented as Unicode and ANSI versions on all platforms.

See Also

Product Query Functions


MsiGetUserInfo

The MsiGetUserInfo function returns the registered user information for an installed product.

USERINFOSTATE MsiGetUserInfo(
  LPCTSTR szProduct,      // product code
  LPTSTR lpUserNameBuf,   // buffer to return user name
  DWORD *pcchUserNameBuf, // buffer character count
  LPTSTR lpOrgNameBuf,    // buffer to return organization name
  DWORD *pcchOrgNameBuf,  // buffer character count, including NULL
  LPTSTR lpSerialBuf,     // buffer to return product ID
  DWORD *pcchSerialBuf    // buffer character count, including NULL
);

Parameters

szProduct
[in] Specifies the product code for the product to be queried.
lpUserNameBuf
[out] Pointer to a variable that receives the name of the user.
pcchUserNameBuf
[in] [out] Pointer to a variable that specifies the size, in characters, of the buffer pointed to by the lpUserNameBuf parameter. This size should include the terminating null character.
lpOrgNameBuf
[out] Pointer to a buffer that receives the organization name.
pcchOrgNameBuf
[in] [out] Pointer to a variable that specifies the size, in characters, of the buffer pointed to by the lpOrgNameBuf parameter. The count does not include the terminating null.
lpSerialBuf
[in] Pointer to a buffer that receives the product ID.
pcchSerialBuf
[in] [out] Pointer to a variable that specifies the size, in characters, of the buffer pointed to by the lpSerialBuf parameter. The count does not include the terminating null.

Return Values

Value | Meaning
USERINFOSTATE_ABSENT | Some or all of the user information is absent.
USERINFOSTATE_INVALIDARG | One of the function parameters was invalid.
USERINFOSTATE_MOREDATA | A buffer is too small to hold the requested data.
USERINFOSTATE_PRESENT | The function completed successfully.
USERINFOSTATE_UNKNOWN | The product code does not identify a known product.

Remarks

When the MsiGetUserInfo function returns, the pcchNameBuf parameter contains the length of the class string stored in the buffer. The count returned does not include the terminating NULL character. If the buffer is not big enough, the MsiGetUserInfo function returns USERINFOSTATE_MOREDATA, and MsiGetUserInfo contains the size of the string, in characters, without counting the NULL character.

The user information is considered to be present even in the absence of a company name.

Requirements

Windows NT/2000: Requires Windows NT 4.0 SP3 or later. Available as a redistributable.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in Msi.h.
Library: Use Msi.lib.
Unicode: Implemented as Unicode and ANSI versions on all platforms.

See Also

System Status Functions


MsiInstallMissingComponent

The MsiInstallMissingComponent function installs files that are unexpectedly missing.

UINT MsiInstallMissingComponent(
  LPCTSTR szProduct,           // product code
  LPCTSTR szComponent,         // component ID
  INSTALLSTATE eInstallState   // install type
);

Parameters

szProduct
[in] Specifies the product code for the product that owns the component to be installed.
szComponent
[in] Identifies the component to be installed.
eInstallState
[in] Specifies the way the component should be installed. This parameter must be one of the following values.
Value | Meaning
INSTALLSTATE_LOCAL | The component should be locally installed.
INSTALLSTATE_SOURCE | The component should be installed to run from the source.
INSTALLSTATE_DEFAULT | The component should be installed according to the installer defaults.

Return Values

Value | Meaning
ERROR_BAD_CONFIGURATION | The configuration information is corrupt.
ERROR_INSTALL_FAILURE | The installation failed.
ERROR_INSTALL_SOURCE_ABSENT | The source was unavailable.
ERROR_INSTALL_SUSPEND | The installation was suspended.
ERROR_INSTALL_USEREXIT | The user exited the installation.
ERROR_INVALID_PARAMETER | One of the parameters is invalid.
ERROR_SUCCESS | The function completed successfully.
ERROR_UNKNOWN_PRODUCT | The product code is unrecognized.

For more information about error messages, see Displayed Error Messages

Remarks

The MsiInstallMissingComponent function resolves the feature(s) that the component belongs to. Then, the product feature that requires the least additional disk space is installed.

Requirements

Windows NT/2000: Requires Windows NT 4.0 SP3 or later. Available as a redistributable.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in Msi.h.
Library: Use Msi.lib.
Unicode: Implemented as Unicode and ANSI versions on all platforms.


MsiInstallMissingFile

The MsiInstallMissingFile function installs files that are unexpectedly missing.

UINT MsiInstallMissingFile(
  LPCTSTR szProduct,      // product code
  LPCTSTR szFile          // file name, without path
);

Parameters

szProduct
[in] Specifies the product code for the product that owns the file to be installed.
szFile
[in] Specifies the file to be installed.

Return Values

Value | Meaning
ERROR_BAD_CONFIGURATION | The configuration information is corrupt.
ERROR_INSTALL_FAILURE | The installation failed.
ERROR_INSTALL_SOURCE_ABSENT | The source was unavailable.
ERROR_INSTALL_SUSPEND | The installation was suspended.
ERROR_INSTALL_USEREXIT | The user exited the installation.
ERROR_INVALID_PARAMETER | A parameter was invalid.
ERROR_SUCCESS | The function completed successfully.
ERROR_UNKNOWN_PRODUCT | The product code is unrecognized.

For more information about error messages, see Displayed Error Messages.

Remarks

The MsiInstallMissingFile function obtains the component that the file belongs to from the file table. Then, the product feature that requires the least additional disk space is installed.

Requirements

Windows NT/2000: Requires Windows NT 4.0 SP3 or later. Available as a redistributable.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in Msi.h.
Library: Use Msi.lib.
Unicode: Implemented as Unicode and ANSI versions on all platforms.

See Also

Installation and Configuration Functions


MsiInstallProduct

The MsiInstallProduct function installs or uninstalls a product.

UINT MsiInstallProduct(
  LPCTSTR szPackagePath,    // path to package
  LPCTSTR szCommandLine     // package command line
);

Parameters

szPackagePath
[in] Specifies the path to the package.
szCommandLine
[in] Specifies the command line property settings. This should be a list of the format Property=Setting Property=Setting. See About Properties.

Return Values

Value | Meaning
ERROR_SUCCESS | The function completed successfully.
An error relating to an action | See Error Codes.
Any Initialization Error | An error relating to initialization occurred.

For more information about error messages, see Displayed Error Messages.

Remarks

The MsiInstallProduct function displays the user interface with the current settings and log mode. You can change user interface settings with the MsiSetInternalUI and MsiSetExternalUI functions. You can set the log mode with the MsiEnableLog function.

Requirements

Windows NT/2000: Requires Windows NT 4.0 SP3 or later. Available as a redistributable.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in Msi.h.
Library: Use Msi.lib.
Unicode: Implemented as Unicode and ANSI versions on all platforms.

See Also

Installation and Configuration Functions, Error Codes, Displayed Error Messages, Initialization Error


MsiLocateComponent

The MsiLocateComponent function returns the full path to an installed component without a product code. This function attempts to determine the product using MsiGetProductCode, but is not guaranteed to find the correct product for the caller. MsiGetComponentPath should always be called when possible.

INSTALLSTATE MsiLocateComponent(
  LPCTSTR szComponent,  // component Id, string GUID
  LPTSTR lpPathBuf,     // returned path
  DWORD *pcchBuf        // in/out buffer character count
);

Parameters

szComponent
[in] Specifies the component ID of the component to be located.
lpPathBuf
[out] Pointer to a variable that receives the path to the component. This parameter can be NULL.
pcchBuf
[in] Pointer to a variable that specifies the size, in characters, of the buffer pointed to by the lpPathBuf parameter. The count does not include the terminating null.

If lpPathBuf is NULL, pcchBuf can be NULL.

Return Values

Value | Meaning
INSTALLSTATE_NOTUSED | The component being requested is disabled on the computer.
INSTALLSTATE_ABSENT | The component is not installed.
INSTALLSTATE_BAD_CONFIGURATION | The configuration data is corrupt.
INSTALLSTATE_INVALIDARG | One of the function parameters is invalid.
INSTALLSTATE_LOCAL | The component is installed locally.
INSTALLSTATE_SOURCE | The component is installed to run from source.
INSTALLSTATE_SOURCEABSENT | The component source is inaccessible.
INSTALLSTATE_UNKNOWN | The product code or component ID is unknown.

Remarks

Upon success of the MsiLocateComponent function, the pcchBuf parameter contains the length of the string in lpPathBuf.

The MsiLocateComponent function might return INSTALLSTATE_ABSENT or INSTALL_STATE_UNKNOWN, for the following reasons:

  • INSTALLSTATE_ABSENT

    The application did not properly ensure that the feature was installed by calling MsiUseFeature and, if necessary, MsiConfigureFeature.

  • INSTALLSTATE_UNKNOWN

    The feature is not published. The application should have determined this earlier by calling MsiQueryFeatureState or MsiEnumFeatures. The application makes these calls while it initializes. An application should only use features that are known to be published. Since INSTALLSTATE_UNKNOWN should have been returned by MsiUseFeature as well, either MsiUseFeature was not called, or its return value was not properly checked.

Requirements

Windows NT/2000: Requires Windows NT 4.0 SP3 or later. Available as a redistributable.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in Msi.h.
Library: Use Msi.lib.
Unicode: Implemented as Unicode and ANSI versions on all platforms.

See Also

Component-Specific Functions


MsiOpenPackage

The MsiOpenPackage function opens a package for use with the functions that access the product database. The MsiCloseHandle function must be called with the handle when the handle is no longer needed.

UINT MsiOpenPackage(
  LPCTSTR szPackagePath,  // the full path to the package
  MSIHANDLE *hProduct     // returned product handle, must be closed
);

Parameters

szPackagePath
[in] Specifies the path to the package.
hProduct
[out] Pointer to a variable that receives the product handle.

Return Values

Value | Meaning
ERROR_BAD_CONFIGURATION | The configuration information is corrupt.
ERROR_INSTALL_FAILURE | The product could not be opened.
ERROR_INVALID_PARAMETER | An invalid parameter was passed to the function.
ERROR_SUCCESS | The function completed successfully.

Remarks

MsiOpenPackage can accept an opened database handle in the form "#nnnn", where nnnn is the database handle in string form, i.e. #123, in lieu of a path to the package. This is intended for development tasks such as running validation actions, or for use with database management tools.

Requirements

Windows NT/2000: Requires Windows NT 4.0 SP3 or later. Available as a redistributable.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in Msi.h.
Library: Use Msi.lib.
Unicode: Implemented as Unicode and ANSI versions on all platforms.

See Also

Product Query Functions


MsiOpenProduct

The MsiOpenProduct function opens a product for use with the functions that access the product database. The MsiCloseHandle function must be called with the handle when the handle is no longer needed.

UINT MsiOpenProduct(
  LPCTSTR szProduct,   // product code
  MSIHANDLE *hProduct  // returned product handle, must be closed
);

Parameters

szProduct
[in] Specifies the product code of the product to be opened.
hProduct
[out] Pointer to a variable that receives the product handle.

Return Values

Value | Meaning
ERROR_BAD_CONFIGURATION | The configuration information is corrupt.
ERROR_INSTALL_FAILURE | The product could not be opened.
ERROR_INSTALL_SOURCE_ABSENT | The source was unavailable.
ERROR_INVALID_PARAMETER | An invalid parameter was passed to the function.
ERROR_SUCCESS | The function completed successfully.
ERROR_UNKNOWN_PRODUCT | The product code was unrecognized.

Requirements

Windows NT/2000: Requires Windows NT 4.0 SP3 or later. Available as a redistributable.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in Msi.h.
Library: Use Msi.lib.
Unicode: Implemented as Unicode and ANSI versions on all platforms.

See Also

Product Query Functions


MsiProvideComponent

The MsiProvideComponent function returns the full component path, performing any necessary installation. This function prompts for source if necessary and increments the usage count for the feature.

UINT MsiProvideComponent(
  LPCTSTR szProduct,    // product code in case install required
  LPCTSTR szFeature,    // feature ID in case install required
  LPCTSTR szComponent,  // component ID
  DWORD dwInstallMode,  // the install mode
  LPTSTR lpPathBuf,     // returned path to component key file
  DWORD *pcchPathBuf    // in/out buffer character count
);

Parameters

szProduct
[in] Specifies the product code for the product that contains the feature with the necessary component.
szFeature
[in] Specifies the feature ID of the feature with the necessary component.
szComponent
[in] Specifies the component code of the necessary component.
dwInstallMode
[out] Defines the installation mode. This parameter can be one of the following values.
Value | Meaning
INSTALLMODE_DEFAULT | Provide the component and perform any installation necessary to provide the component. If the key file of a component in the requested feature, or a feature parent, is missing, reinstall the feature using MsiReinstallFeature with the following flag bits set: REINSTALLMODE_FILEMISSING, REINSTALLMODE_FILEOLDERVERSION, REINSTALLMODE_FILEVERIFY, REINSTALLMODE_MACHINEDATA, REINSTALLMODE_USERDATA and REINSTALLMODE_SHORTCUT.
INSTALLMODE_EXISTING Provide the component only if the feature exists. Otherwise return ERROR_FILE_NOT_FOUND.

This mode verifies that the key file of the component exists.
INSTALLMODE_NODETECTION Provide the component only if the feature exists. Otherwise return ERROR_FILE_NOT_FOUND.

This mode only checks that the component is registered and does not verify that the key file of the component exists.
combination of the
REINSTALLMODE flags 		Call MsiReinstallFeature to reinstall feature using this parameter for the dwReinstallMode parameter, and then provide the component.
INSTALLMODE_NOSOURCERESOLUTION | Provide the component only if the feature's installation state is INSTALLSTATE_LOCAL. If the feature's installation state is INSTALLSTATE_SOURCE, return ERROR_INSTALL_SOURCE_ABSENT. Otherwise return ERROR_FILE_NOT_FOUND. This mode only checks that the component is registered and does not verify that the key file exists.

lpPathBuf
[out] Pointer to a variable that receives the path to the component. This parameter can be NULL.
pcchPathBuf
[out] Pointer to a variable that specifies the size, in characters, of the buffer pointed to by the lpPathBuf parameter. The count does not include the terminating null.

If lpPathBuf is NULL, pcchBuf can be NULL.

Return Values

Value | Meaning
ERROR_BAD_CONFIGURATION | The configuration data is corrupt.
ERROR_FILE_NOT_FOUND | The feature is absent or broken. this error is returned for dwInstallMode = INSTALLMODE_EXISTING.
ERROR_INSTALL_FAILURE | The installation failed.
ERROR_INSTALL_NOTUSED | The component being requested is disabled on the computer.
ERROR_INVALID_PARAMETER | An invalid parameter was passed to the function.
ERROR_SUCCESS | The function completed successfully.
ERROR_UNKNOWN_FEATURE | The feature ID does not identify a known feature.
ERROR_UNKNOWN_PRODUCT | The product code does not identify a known product.
INSTALLSTATE_UNKNOWN | An unrecognized product or a feature name was passed to the function.
ERROR_MORE_DATA | The buffer overflow is returned.
ERROR_INSTALL_SOURCE_ABSENT | Unable to detect a source.

For more information, see Displayed Error Messages.

Remarks

Upon success of the MsiProvideComponent function, the pcchPathBuf parameter contains the length of the string in lpPathBuf.

The MsiProvideComponent function combines the functionality of MsiUseFeature, MsiConfigureFeature, and MsiGetComponentPath. You can use the MsiProvideComponent function to simplify the calling sequence. However, because this function increments the usage count, use it with caution to prevent inaccurate usage counts. The MsiProvideComponent function also provides less flexibility than the series of individual calls.

If the application is recovering from an unexpected situation, the application has probably already called MsiUseFeature and incremented the usage count. In this case, the application should call MsiConfigureFeature instead of MsiProvideComponent to avoid incrementing the count again.

The INSTALLMODE_EXISTING option cannot be used in combination with the REINSTALLMODE flag.

Features with components containing a corrupted file or the wrong version of a file must be explicitly reinstalled by the user or by having the application call MsiReinstallFeature.

Requirements

Windows NT/2000: Requires Windows NT 4.0 SP3 or later. Available as a redistributable.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in Msi.h.
Library: Use Msi.lib.
Unicode: Implemented as Unicode and ANSI versions on all platforms.

See Also

Component-Specific Functions


MsiProvideQualifiedComponent

The MsiProvideQualifiedComponent function returns the full component path for a qualified component and performs any necessary installation. This function prompts for source if necessary and increments the usage count for the feature.

UINT MsiProvideQualifiedComponent(
  LPCTSTR szComponent,  // component ID
  LPCTSTR szQualifier,  // specifies which component to access
  DWORD dwInstallMode,  // the install mode
  LPTSTR lpPathBuf,     // in/out returned path, NULL if not needed
  DWORD *pcchPathBuf    // in/out buffer character count
);

Parameters

szComponent
[in] Specifies the component ID that for the requested component. This may not be the GUID for the component itself but rather a server that provides the correct functionality, as in the ComponentId column of the PublishComponent table.
szQualifier
[in] Specifies a qualifier into a list of advertising components (from PublishComponent Table).
dwInstallMode
[in] Defines the installation mode. This parameter can be one of the following values.
Value | Meaning
INSTALLMODE_DEFAULT | Provide the component and perform any installation necessary to provide the component. If the key file of a component in the requested feature, or a feature parent, is missing, reinstall the feature using MsiReinstallFeature with the following flag bits set: REINSTALLMODE_FILEMISSING, REINSTALLMODE_FILEOLDERVERSION, REINSTALLMODE_FILEVERIFY, REINSTALLMODE_MACHINEDATA, REINSTALLMODE_USERDATA and REINSTALLMODE_SHORTCUT.
INSTALLMODE_EXISTING Provide the component only if the feature exists. Otherwise return ERROR_FILE_NOT_FOUND.

This mode verifies that the key file of the component exists.
INSTALLMODE_NODETECTION Provide the component only if the feature exists. Otherwise return ERROR_FILE_NOT_FOUND.

This mode only checks that the component is registered and does not verify that the key file of the component exists.
INSTALLMODE_EXISTING | Provide the component only if the feature exists, else return ERROR_FILE_NOT_FOUND.
combination of the
REINSTALLMODE flags 		Call MsiReinstallFeature to reinstall feature using this parameter for the dwReinstallMode parameter, and then provide the component.
INSTALLMODE_NOSOURCERESOLUTION | Provide the component only if the feature's installation state is INSTALLSTATE_LOCAL. If the feature's installation state is INSTALLSTATE_SOURCE, return ERROR_INSTALL_SOURCE_ABSENT. Otherwise return ERROR_FILE_NOT_FOUND. This mode only checks that the component is registered and does not verify that the key file exists.

lpPathBuf
[in] [out] Pointer to a variable that receives the path to the component. This parameter can be NULL.
pcchPathBuf
[in] [out] Pointer to a variable that specifies the size, in characters, of the buffer pointed to by the lpPathBuf parameter. The count does not include the terminating null.

If lpPathBuf is NULL, pcchBuf can be NULL.

Return Values

Value | Meaning
ERROR_INDEX_ABSENT | Component qualifier invalid or not present.
ERROR_SUCCESS | The function completed successfully.
ERROR_FILE_NOT_FOUND | The feature is absent or broken. this error is returned for dwInstallMode = INSTALLMODE_EXISTING.
ERROR_UNKNOWN_COMPONENT | The specified component is unknown.
An error relating to an action | See Error Codes.
Any Initialization Error | An error relating to initialization occurred.

Remarks

Upon success of the MsiProvideQualifiedComponent function, the pcchPathBuf parameter contains the length of the string in lpPathBuf.

Features with components containing a corrupted file or the wrong version of a file must be explicitly reinstalled by the user or by having the application call MsiReinstallFeature.

Requirements

Windows NT/2000: Requires Windows NT 4.0 SP3 or later. Available as a redistributable.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in Msi.h.
Library: Use Msi.lib.
Unicode: Implemented as Unicode and ANSI versions on all platforms.

See Also

Component-Specific Functions, Error Codes, Displayed Error Messages, Initialization Error


MsiProvideQualifiedComponentEx

The MsiProvideQualifiedComponentEx function returns the full component path for a qualified component that is published by a product and performs any necessary installation. This function prompts for source if necessary and increments the usage count for the feature.

UINT MsiProvideQualifiedComponentEx(
  LPCTSTR szComponent,  // component ID
  LPCTSTR szQualifier,  // specifies which component to access
  DWORD dwInstallMode,  // the install mode
  LPTSTR szProduct,     // specifies the product to match that has
                        // published the qualified component
  DWORD dwUnused1,      // unused, must be zero
  DWORD dwUnused2,      // unused, must be zero
  LPTSTR lpPathBuf,     // in/out returned path, Null if not needed
  DWORD *pcchPathBuf    // in/out buffer character count
);

Parameters

szComponent
[in] Specifies the component ID that for the requested component. This may not be the GUID for the component itself but rather a server that provides the correct functionality, as in the ComponentId column of the PublishComponent table.
szQualifier
[in] Specifies a qualifier into a list of advertising components (from PublishComponent Table).
dwInstallMode
[in] Defines the installation mode. This parameter can be one of the following values.
Value | Meaning
INSTALLMODE_DEFAULT | Provide the component and perform any installation necessary to provide the component. If the key file of a component in the requested feature, or a feature parent, is missing, reinstall the feature using MsiReinstallFeature with the following flag bits set: REINSTALLMODE_FILEMISSING, REINSTALLMODE_FILEOLDERVERSION, REINSTALLMODE_FILEVERIFY, REINSTALLMODE_MACHINEDATA, REINSTALLMODE_USERDATA and REINSTALLMODE_SHORTCUT.
INSTALLMODE_EXISTING Provide the component only if the feature exists. Otherwise return ERROR_FILE_NOT_FOUND.

This mode verifies that the key file of the component exists.
INSTALLMODE_NODETECTION Provide the component only if the feature exists. Otherwise return ERROR_FILE_NOT_FOUND.

This mode only checks that the component is registered and does not verify that the key file of the component exists.
INSTALLMODE_EXISTING | Provide the component only if the feature exists, else return ERROR_FILE_NOT_FOUND.
combination of the
REINSTALLMODE flags 		Call MsiReinstallFeature to reinstall feature using this parameter for the dwReinstallMode parameter, and then provide the component.
INSTALLMODE_NOSOURCERESOLUTION | Provide the component only if the feature's installation state is INSTALLSTATE_LOCAL. If the feature's installation state is INSTALLSTATE_SOURCE, return ERROR_INSTALL_SOURCE_ABSENT. Otherwise return ERROR_FILE_NOT_FOUND. This mode only checks that the component is registered and does not verify that the key file exists.

szProduct
[in] Specifies the product to match that has published the qualified component. If this is null, then this API works the same as MsiProvideQualifiedComponent.
dwUnused1
[in] Reserved. Must be zero.
dwUnused2
[in] Reserved. Must be zero.
lpPathBuf
[out] Pointer to a variable that receives the path to the component. This parameter can be NULL.
pcchPathBuf
[out] Pointer to a variable that specifies the size, in characters, of the buffer pointed to by the lpPathBuf parameter. The count does not include the terminating null.

If lpPathBuf is NULL, pcchBuf can be NULL.

Return Values

Value | Meaning
ERROR_INDEX_ABSENT | Component qualifier invalid or not present.
ERROR_SUCCESS | The function completed successfully.
ERROR_FILE_NOT_FOUND | The feature is absent or broken. this error is returned for dwInstallMode = INSTALLMODE_EXISTING.
ERROR_UNKNOWN_COMPONENT | The specified component is unknown.
An error relating to an action | See Error Codes.
Any Initialization Error | An error relating to initialization occurred.

Remarks

Upon success of the MsiProvideQualifiedComponentEx function, the pcchPathBuf parameter contains the length of the string in lpPathBuf.

Features with components containing a corrupted file or the wrong version of a file must be explicitly reinstalled by the user or by having the application call MsiReinstallFeature.

Requirements

Windows NT/2000: Requires Windows NT 4.0 SP3 or later. Available as a redistributable.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in Msi.h.
Library: Use Msi.lib.
Unicode: Implemented as Unicode and ANSI versions on all platforms.

See Also

Component-Specific Functions, Error Codes, Initialization Error, Displayed Error Messages


MsiQueryFeatureState

The MsiQueryFeatureState function returns the installed state for a product feature.

INSTALLSTATE MsiQueryFeatureState(
  LPCTSTR szProduct,    // product code
  LPCTSTR szFeature     // feature ID
);

Parameters

szProduct
[in] Specifies the product code for the product that contains the feature of interest.
szFeature
[in] Identifies the feature of interest.

Return Values

Value | Meaning
INSTALLSTATE_ABSENT | The feature is not installed.
INSTALLSTATE_ADVERTISED | The feature is advertised
INSTALLSTATE_LOCAL | The feature is installed locally.
INSTALLSTATE_SOURCE | The feature is installed to run from source.
INSTALLSTATE_INVALIDARG | An invalid parameter was passed to the function.
INSTALLSTATE_UNKNOWN | The product code or feature ID is unknown.
INSTALLSTATE_BAD_CONFIGURATION | The configuration data is corrupt.

Remarks

The MsiQueryFeatureState function does not validate that the feature is actually accessible.

Requirements

Windows NT/2000: Requires Windows NT 4.0 SP3 or later. Available as a redistributable.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in Msi.h.
Library: Use Msi.lib.
Unicode: Implemented as Unicode and ANSI versions on all platforms.

See Also

System Status Functions


MsiQueryProductState

The MsiQueryProductState function returns the installed state for a product.

INSTALLSTATE MsiQueryProductState(
  LPCTSTR szProduct  // product code
);

Parameters

szProduct
[in] Specifies the product code that identifies the product to be queried.

Return Values

Value | Meaning
INSTALLSTATE_ABSENT | The product is installed for a different user.
INSTALLSTATE_ADVERTISED | The product is advertised but not installed.
INSTALLSTATE_BAD_CONFIGURATION | The configuration data is corrupt.
INSTALLSTATE_DEFAULT | The product is installed for the current user.
INSTALLSTATE_INVALIDARG | An invalid parameter was passed to the function.
INSTALLSTATE_UNKNOWN | The product is neither advertised or installed.

Requirements

Windows NT/2000: Requires Windows NT 4.0 SP3 or later. Available as a redistributable.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in Msi.h.
Library: Use Msi.lib.
Unicode: Implemented as Unicode and ANSI versions on all platforms.

See Also

System Status Functions


MsiReinstallFeature

The MsiReinstallFeature function reinstalls features.

UINT MsiReinstallFeature(
  LPCTSTR szProduct,       // product code
  LPCTSTR szFeature,       // feature ID
  LPCTSTR dwReinstallMode  // one or more REINSTALLMODE modes
);

Parameters

szProduct
[in] Specifies the product code for the product containing the feature to be reinstalled.
szFeature
[in] Identifies the feature to be reinstalled.
dwReinstallMode
[in] Specifies what to install. This parameter can be one or more of the following values.
Value | Meaning
REINSTALLMODE_FILEMISSING | Reinstall only if the file is missing.
REINSTALLMODE_FILEOLDERVERSION | Reinstall if the file is missing or is an older version.
REINSTALLMODE_FILEEQUALVERSION | Reinstall if the file is missing or is an equal or older version.
REINSTALLMODE_FILEEXACT | Reinstall if the file is missing or is not an exact version.
REINSTALLMODE_FILEVERIFY | Check sum executables, and reinstall if they are missing or corrupt. This flag only repairs files that have msidbFileAttributesChecksum in the Attributes column of the File table.
REINSTALLMODE_FILEREPLACE | Reinstall all files regardless of version.
REINSTALLMODE_USERDATA | Ensure required per-user registry entries.
REINSTALLMODE_MACHINEDATA | Ensure required per-machine registry entries.
REINSTALLMODE_SHORTCUT | Validate shortcuts.
REINSTALLMODE_PACKAGE | Use the re-cache source to install the package.

Return Values

Value | Meaning
ERROR_INSTALL_FAILURE | The installation failed.
ERROR_INVALID_PARAMETER | An invalid parameter was passed to the function.
ERROR_INSTALL_SERVICE_FAILURE | The installation service could not be accessed.
ERROR_INSTALL_SUSPEND | The installation was suspended and is incomplete.
ERROR_INSTALL_USEREXIT | The user canceled the installation.
ERROR_SUCCESS | The function completed successfully.
ERROR_UNKNOWN_FEATURE | The feature ID does not identify a known feature.
ERROR_UNKNOWN_PRODUCT | The product code does not identify a known product.

For more information, see Displayed Error Messages

Requirements

Windows NT/2000: Requires Windows NT 4.0 SP3 or later. Available as a redistributable.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in Msi.h.
Library: Use Msi.lib.
Unicode: Implemented as Unicode and ANSI versions on all platforms.

See Also

Installation and Configuration Functions


MsiReinstallProduct

The MsiReinstallProduct function reinstalls products.

UINT MsiReinstallProduct(
  LPCTSTR szProduct,        // product code
  DWORD dwReinstallMode     // one or more REINSTALLMODE modes
);

Parameters

szProduct
[in] Specifies the product code for the product to be reinstalled.
dwReinstallMode
[in] Specifies the reinstall mode. This parameter can be one or more of the following values.
Value | Meaning
REINSTALLMODE_FILEMISSING | Reinstall only if the file is missing.
REINSTALLMODE_FILEOLDERVERSION | Reinstall if the file is missing or is an older version.
REINSTALLMODE_FILEEQUALVERSION | Reinstall if the file is missing or is an equal or older version.
REINSTALLMODE_FILEEXACT | Reinstall if the file is missing or is not an exact version.
REINSTALLMODE_FILEVERIFY | Check sum executables, and reinstall if they are missing or corrupt. This flag only repairs files that have msidbFileAttributesChecksum in the Attributes column of the File table.
REINSTALLMODE_FILEREPLACE | Reinstall all the files regardless of version.
REINSTALLMODE_USERDATA | Ensure required per-user registry entries.
REINSTALLMODE_MACHINEDATA | Ensure required per-machine registry entries.
REINSTALLMODE_SHORTCUT | Validate shortcuts.
REINSTALLMODE_PACKAGE | Use the re-cache source to install the package.

Return Values

Value | Meaning
ERROR_INSTALL_FAILURE | The installation failed.
ERROR_INVALID_PARAMETER | An invalid parameter was passed to the function.
ERROR_INSTALL_SERVICE_FAILURE | The installation service could not be accessed.
ERROR_INSTALL_SUSPEND | The installation was suspended and is incomplete.
ERROR_INSTALL_USEREXIT | The user canceled the installation.
ERROR_SUCCESS | The function completed successfully.
ERROR_UNKNOWN_PRODUCT | The product code does not identify a known product.

For more information, see Displayed Error Messages.

Requirements

Windows NT/2000: Requires Windows NT 4.0 SP3 or later. Available as a redistributable.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in Msi.h.
Library: Use Msi.lib.
Unicode: Implemented as Unicode and ANSI versions on all platforms.

See Also

Installation and Configuration Functions


MsiSetExternalUI

The MsiSetExternalUI function enables an external user-interface handler. This external UI handler is called before the normal internal user-interface handler. The external UI handler has the option to suppress the internal UI by returning a non-zero value to indicate that it has handled the messages. For more information, see About the User Interface.

INSTALLUI_HANDLER MsiSetExternalUI(
  INSTALLUI_HANDLER puiHandler, // UI handler
  DWORD dwMessageFilter,        // bit flags designating which messages to handle
  LPVOID pvContext              // application context
);

Parameters

puiHandler
[in] Specifies a callback function that conforms to the INSTALLUI_HANDLER specification.
dwMessageFilter
[in] Specifies which messages to handle using the external message handler. If the external handler returns a non-zero result, then that message will not be sent to the UI, instead the message will be logged if logging has been enabled. See MsiEnableLog.
Value | Meaning
INSTALLLOGMODE_FATALEXIT | Premature termination of installation.
INSTALLLOGMODE_ERROR | The error messages are logged.
INSTALLLOGMODE_WARNING | The warning messages are logged.
INSTALLLOGMODE_USER | The user requests are logged.
INSTALLLOGMODE_INFO | The status messages that are not displayed are logged.
INSTALLLOGMODE_RESOLVESOURCE | Request to determine a valid source location.
INSTALLLOGMODE_OUTOFDISKSPACE | The was insufficient disk space.
INSTALLLOGMODE_ACTIONSTART | The start of new installation actions are logged.
INSTALLLOGMODE_ACTIONDATA | The data record with the installation action is logged.
INSTALLLOGMODE_COMMONDATA | The parameters for user-interface initialization are logged.
INSTALLLOGMODE_PROGRESS | Progress bar information. This message includes information on units so far and total number of units. See MsiProcessMessage for an explanation of the message format. This message is only sent to an external user interface and is not logged.
INSTALLLOGMODE_INITIALIZE | If this is not a quiet installation, then the basic UI has been initialized. If this is a full UI installation, the Full UI is not yet initialized. This message is only sent to an external user interface and is not logged.
INSTALLLOGMODE_TERMINATE | If a full UI is being used, the full UI has ended. If this is not a quiet installation, the basic UI has not yet ended. This message is only sent to an external user interface and is not logged.
INSTALLLOGMODE_SHOWDIALOG | Sent prior to display of the Full UI dialog. This message is only sent to an external user interface and is not logged.

pvContext
[out] Pointer to an application context that is passed to the callback function. This parameter can be used for error checking.

Return Values

The return value is the previously set external handler, or 0 if there was no previously set handler.

Remarks

To restore the previous UI handler, second call is made to MsiSetExternalUI using the INSTALLUI_HANDLER returned by the first call to MsiSetExternalUI and specifying 0 for dwMessageFilter.

The external user interface handler pointed to by the puiHandler parameter does not have full control over the external user interface unless MsiSetInternalUI is called with the dwUILevel parameter set to INSTALLUILEVEL_NONE. If MsiSetInternalUI is not called, the internal user interface level defaults to INSTALLUILEVEL_BASIC. As a result, any message not handled by the external user interface handler is handled by Windows Installer. The initial "Preparing to install. . ." dialog always appears even if the external user interface handler handles all messages.

Although it is possible to call MsiSetExternalUI from within a custom action, this is not recommended. The recommended practice is to call MsiSetExternalUI from a bootstrapping application.

Requirements

Windows NT/2000: Requires Windows NT 4.0 SP3 or later. Available as a redistributable.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in Msi.h.
Library: Use Msi.lib.
Unicode: Implemented as Unicode and ANSI versions on all platforms.

See Also

Interface and Logging Functions


MsiSetInternalUI

The MsiSetInternalUI function enables the installer's internal user interface. Then this user interface is used for all subsequent calls to user-interface-generating installer functions in this process. For more information, see User Interface Levels.

INSTALLUILEVEL MsiSetInternalUI(
  INSTALLUILEVEL dwUILevel,  // UI level
  HWND *phWnd                // handle of owner window
);

Parameters

dwUILevel
[in] Specifies the level of complexity of the user interface. This parameter can be one of the following values.
Value | Meaning
INSTALLUILEVEL_FULL | Authored user interface with wizards, progress, and errors.
INSTALLUILEVEL_REDUCED | Authored user interface with wizard dialog boxes suppressed.
INSTALLUILEVEL_BASIC | Simple progress and error handling.
INSTALLUILEVEL_DEFAULT | The installer chooses an appropriate user interface level.
INSTALLUILEVEL_NONE | Completely silent installation.
INSTALLUILEVEL_ENDDIALOG | If combined with any above value, the installer displays a modal dialog box at the end of a successful installation or if there has been an error. No dialog box is displayed if the user cancels.
INSTALLUILEVEL_PROGRESSONLY | If combined with the INSTALLUILEVEL_BASIC value, the installer shows simple progress dialog boxes but does not display any modal dialog boxes or error dialog boxes.
INSTALLUILEVEL_NOCHANGE | No change in the UI level. However, if phWnd is not Null, the parent window can change.

phWnd
[in] [out] Pointer to a window. This window becomes the owner of any user interface created. A pointer to the previous owner of the user interface is returned. If this parameter is NULL, the owner of the user interface does not change.

Return Values

The previous user interface level is returned. If an invalid dwUILevel is passed, then INSTALLUILEVEL_NOCHANGE is returned.

Remarks

The MsiSetInternalUI function is useful when the installer must display a user interface. For example, if a feature is installed, but the source is a compact disc that must be inserted, the installer prompts the user for the compact disc. Depending on the nature of the installation, the application might also display progress indicators or query the user for information.

When Msi.dll is loaded, the user interface level is set to DEFAULT and the user interface owner is set to 0 (that is, the initial user interface owner is the desktop).

Requirements

Windows NT/2000: Requires Windows NT 4.0 SP3 or later. Available as a redistributable.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in Msi.h.
Library: Use Msi.lib.

See Also

Interface and Logging Functions


MsiSourceListAddSource

The MsiSourceListAddSource function adds to the list of valid network sources in the source list.

For Windows Installer versions earlier than version 1.5, the SOURCELIST property is limited to a maximum of 26 network sources plus 26 URL sources. For Windows Installer version 1.5 and later, the number of sources in the SOURCELIST property is unlimited. For Windows Installer version 1.1 and later MsiSourceListAddSource may be used to add network sources beyond the limit of 26.

UINT MsiSourceListAddSource(
  LPCTSTR szProduct,     // product code
  LPCTSTR szUserName,    // user name or NULL
  DWORD dwReserved,      // reserved, must be 0
  LPCTSTR szSource       // pointer
);

Parameters

szProduct
[in] Specifies the product code.
szUserName
[in] User name for per-user installation; NULL or empty string for per-machine installation. The user name should always be in the format of DOMAIN\USERNAME (or MACHINENAME\USERNAME for a local user).
dwReserved
[in] Reserved for future use. This value must be set to 0.
szSource
[in] Pointer to the string specifying the source.

Return Values

Value | Meaning
ERROR_INVALID_PARAMETER | An invalid parameter was passed to the function.
ERROR_SUCCESS | The source was added.
ERROR_UNKNOWN_PRODUCT | The specified product is unknown.
ERROR_FUNCTION_FAILED | The function did not succeed.
ERROR_ACCESS_DENIED | The user does not have the ability to add a source.
ERROR_BAD_USERNAME | Could not resolve the user name.
ERROR_INSTALL_SERVICE_FAILURE | Could not access installer service
ERROR_BAD_CONFIGURATION | The configuration data is corrupt.

Remarks

An administrator can modify per-user non-managed installations for himself/herself, per-machine installations, and per-user managed installations for any user. Non-administrators can only modify their own installations (managed or non-managed) and per-machine installations, and then only if they are allowed to browse for a source for the product. For more information, see DisableBrowse, AllowLockdownBrowse, and AlwaysInstallElevated policies.

Note that the newly added source is merely added to the set of valid sources. If another source in the set was used to install the product, the new source is not used until the current source is unavailable.

It is the responsibility of the caller to ensure that the provided source is a valid source image for the product.

If the user name is an empty string or NULL, the function operates on the per-machine install of the product. If the product is installed, but is a per-user install, the function returns ERROR_UNKNOWN_PRODUCT.

If the user name argument is non-empty, it specifies the name of the user whose product install is modified. If the current user name is provided, the function first attempts to modify a non-managed installation. If no product is found, the function then tries the same product but managed per-user. If the product is not found in either place, the function returns ERROR_UNKNOWN_PRODUCT, even if the product is installed per-machine.

If the user name does not belong to the current user, the function only checks the managed product for the specified user. It is not possible to modify a non-managed installation for a user besides the current one. If the product is not installed in a managed per-user state for the specified user, the function returns ERROR_UNKNOWN_PRODUCT, even if the product is installed per-machine.

This function is not available with Windows Installer version 1.0.

Requirements

Windows NT/2000: Requires Windows NT 4.0 SP3 or later. Available as a redistributable.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in Msi.h.
Library: Use Msi.lib.
Unicode: Implemented as Unicode and ANSI versions on all platforms.

See Also

Source Resiliency, DisableBrowse, AllowLockdownBrowse, AlwaysInstallElevated


MsiSourceListClearAll

The MsiSourceListClearAll function removes all network sources from the source list. For more information, see Source Resiliency.

UINT MsiSourceListClearAll(
  LPCTSTR szProduct,     // product code
  LPCTSTR szUserName,    // user name or NULL
  DWORD dwReserved       // reserved, must be 0
);

Parameters

szProduct
[in] Specifies the product code.
szUserName
[in] User name for per-user installation; NULL or empty string for per-machine installation. The user name should always be in the format of DOMAIN\USERNAME (or MACHINENAME\USERNAME for a local user).
dwReserved
[in] Reserved for future use. This value must be set to 0.

Return Values

Value | Meaning
ERROR_INVALID_PARAMETER | An invalid parameter was passed to the function.
ERROR_SUCCESS | The function succeeded
ERROR_UNKNOWN_PRODUCT | The specified product is unknown.
ERROR_FUNCTION_FAILED | The function did not succeed.
ERROR_ACCESS_DENIED | The user does not have the ability to clear the source list for this product.
ERROR_BAD_USERNAME | Could not resolve the user name.
ERROR_INSTALL_SERVICE_FAILURE | Could not access installer service
ERROR_BAD_CONFIGURATION | The configuration data is corrupt.

Remarks

An administrator can modify per-user non-managed installations for himself/herself, per-machine installations, and per-user managed installations for any user. Non-administrators can only modify their own installations (managed or non-managed) and per-machine installations, and then only if they are allowed to browse for a source for the product. For more information, see DisableBrowse, AllowLockdownBrowse, and AlwaysInstallElevated policies.

If a network source is the current source for the product, this function forces the installer to search the source list for a valid source the next time a source is needed. If the current source is media or a URL source, it is still valid after this call and the source list is not searched unless MsiSourceListForceResolution is also called.

If the user name is an empty string or NULL, the function operates on the per-machine installation of the product. If the product is installed, but it is a per-user install, the function returns ERROR_UNKNOWN_PRODUCT.

If the user name argument is non-empty, it specifies the name of the user whose product install is modified. If the current user name is provided, the function first attempts to modify a non-managed install. If no product is found, the function then tries the same product but managed per-user. If the product is not found in either place, the function returns ERROR_UNKNOWN_PRODUCT, even if the product is installed per-machine.

If the user name does not belong to the current user, the function only checks the managed product for the specified user. It is not possible to modify a non-managed install for a user other than the current one. If the product is not installed in a managed per-user state for the specified user, the function returns ERROR_UNKNOWN_PRODUCT, even if the product is installed per-machine.

This function is not available with Windows Installer version 1.0.

Requirements

Windows NT/2000: Requires Windows NT 4.0 SP3 or later. Available as a redistributable.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in Msi.h.
Library: Use Msi.lib.
Unicode: Implemented as Unicode and ANSI versions on all platforms.


MsiSourceListForceResolution

The MsiSourceListForceResolution function forces the installer to search the source list for a valid product source the next time a source is needed. For example, when the installer performs an installation or reinstallation, or when it needs the path for a component that is set to run from source.

UINT MsiSourceListForceResolution(
  LPCTSTR szProduct,     // product code
  LPCTSTR szUserName,    // user name or NULL
  DWORD dwReserved       // reserved, must be 0
);

Parameters

szProduct
[in] Specifies the product code.
szUserName
[in] User name for per-user installation; NULL or empty string for per-machine installation. The user name should always be in the format of DOMAIN\USERNAME (or MACHINENAME\USERNAME for a local user).
dwReserved
[in] Reserved for future use. This value must be set to 0.

Return Values

Value | Meaning
ERROR_INVALID_PARAMETER | An invalid parameter was passed to the function.
ERROR_SUCCESS | The function succeeded.
ERROR_UNKNOWN_PRODUCT | The specified product is unknown.
ERROR_FUNCTION_FAILED | The function could not complete.
ERROR_ACCESS_DENIED | The caller does not have sufficient access to force resolution for the product.
ERROR_BAD_USER_NAME | The specified user is not a valid user.
ERROR_INSTALL_SERVICE_FAILURE | The installation service could not be accessed.
ERROR_BAD_CONFIGURATION | The configuration data is corrupt.

Remarks

An administrator can force resolution for per-user non-managed installations for himself/herself, per-machine installations, and per-user managed installations for any user. Non-administrators can only force a resolution for their own installations (managed or non-managed) and per-machine installations.

If the user name is an empty string or NULL, the function operates on the per-machine install of the product. If the product is installed, but is a per-user installation, the function returns ERROR_UNKNOWN_PRODUCT.

If the user name argument is non-empty, it specifies the name of the user whose product installation will be modified. If the current user name is provided, the function first attempts to modify a non-managed install. If no product is found, the function then tries the same product but managed per-user. If the product is not found in either place, the function returns ERROR_UNKNOWN_PRODUCT, even if the product is installed per-machine.

If the user name does not belong to the current user, the function only checks the managed product for the specified user. It is not possible to modify a non-managed install for a user other than the current one. If the product is not installed in a managed per-user state for the specified user, the function returns ERROR_UNKNOWN_PRODUCT, even if the product is installed per-machine.

This function is not available with Windows Installer version 1.0.

Requirements

Windows NT/2000: Requires Windows NT 4.0 SP3 or later. Available as a redistributable.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in Msi.h.
Library: Use Msi.lib.
Unicode: Implemented as Unicode and ANSI versions on all platforms.

See Also

Source Resiliency, MsiGetComponentPath


MsiUseFeature

The MsiUseFeature function increments the usage count for a particular feature and indicates the installation state for that feature. This function should be used to indicate an application's intent to use a feature.

INSTALLSTATE MsiUseFeature(
  LPCTSTR szProduct,   // product that owns the feature
  LPCTSTR szFeature    // feature to be used
);

Parameters

szProduct
[in] Specifies the product code for the product that owns the feature to be used.
szFeature
[in] Identifies the feature to be used.

Return Values

Value | Meaning
INSTALLSTATE_ABSENT | The feature is not installed.
INSTALLSTATE_ADVERTISED | The feature is advertised
INSTALLSTATE_BADCONFIG | The configuration data is corrupt.
INSTALLSTATE_INVALIDARG | Invalid function argument.
INSTALLSTATE_LOCAL | The feature is locally installed and available for use.
INSTALLSTATE_SOURCE | The feature is installed from the source and available for use.
INSTALLSTATE_UNKNOWN | The feature is not published.

Remarks

The MsiUseFeature function should only be used on features known to be published. INSTALLSTATE_UNKNOWN indicates that the program is trying to use a feature that is not published. The application should determine whether the feature is published before calling MsiUseFeature by calling MsiQueryFeatureState or MsiEnumFeatures. The application should make these calls while it initializes. An application should only use features that are known to be published.

Requirements

Windows NT/2000: Requires Windows NT 4.0 SP3 or later. Available as a redistributable.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in Msi.h.
Library: Use Msi.lib.
Unicode: Implemented as Unicode and ANSI versions on all platforms.

See Also

Application-Only Functions


MsiUseFeatureEx

The MsiUseFeatureEx function increments the usage count for a particular feature and indicates the installation state for that feature. This function should be used to indicate an application's intent to use a feature.

INSTALLSTATE MsiUseFeatureEx(
  LPCTSTR szProduct,    // product that owns the feature
  LPCTSTR szFeature,    // feature to be used
  DWORD dwInstallMode,  // the install mode
  DWORD dwReserved      // must be 0
);

Parameters

szProduct
[in] Specifies the product code for the product that owns the feature to be used.
szFeature
[in] Identifies the feature to be used.
dwInstallMode
[in] This parameter can have the following value.
Value | Meaning
INSTALLMODE_NODETECTION | Return value indicates the installation state.

dwReserved
[in] Reserved for future use. This value must be set to 0.

Return Values

Value | Meaning
INSTALLSTATE_ABSENT | The feature is not installed.
INSTALLSTATE_ADVERTISED | The feature is advertised
INSTALLSTATE_LOCAL | The feature is locally installed and available for use.
INSTALLSTATE_SOURCE | The feature is installed from the source and available for use.
INSTALLSTATE_UNKNOWN | The feature is not published.

Remarks

The MsiUseFeatureEx function should only be used on features known to be published. INSTALLSTATE_UNKNOWN indicates that the program is trying to use a feature that is not published. The application should determine whether the feature is published before calling MsiUseFeature by calling MsiQueryFeatureState or MsiEnumFeatures. The application should make these calls while it initializes. An application should only use features that are known to be published.

Requirements

Windows NT/2000: Requires Windows NT 4.0 SP3 or later. Available as a redistributable.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in Msi.h.
Library: Use Msi.lib.
Unicode: Implemented as Unicode and ANSI versions on all platforms.

See Also

Application-Only Functions


MsiVerifyPackage

The MsiVerifyPackage function verifies that the given file is an installation package.

UINT MsiVerifyPackage(
  LPCTSTR szPackagePath  // location of package
);

Parameters

szPackagePath
[in] Specifies the path and file name of the package.

Return Values

Value | Meaning
ERROR_INSTALL_PACKAGE_INVALID | The file is not a valid package.
ERROR_INSTALL_PACKAGE_OPEN_FAILED | The file could not be opened.
ERROR_INVALID_PARAMETER | The parameter is not valid.
ERROR_SUCCESS | The file is a package.

Requirements

Windows NT/2000: Requires Windows NT 4.0 SP3 or later. Available as a redistributable.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in Msi.h.
Library: Use Msi.lib.
Unicode: Implemented as Unicode and ANSI versions on all platforms.


Initialization Errors

Error code | Error
ERROR_SUCCESS | Initialization complete
ERROR_ALREADY_INITIALIZED | The installer is already initialized
ERROR_INVALID_COMMAND_LINE | Invalid command line syntax
ERROR_INSTALL_ALREADY_RUNNING | An installation is already in progress
ERROR_INSTALL_PACKAGE_OPEN_FAILED | Database could not be opened
ERROR_INSTALL_PACKAGE_INVALID | Incompatible database
ERROR_INSTALL_PACKAGE_VERSION | Installer version does not support database format
ERROR_INSTALL_PLATFORM_UNSUPPORTED | The platform specified by the Template Summary property is not supported.
ERROR_INSTALL_SERVICE_FAILURE | Install server could not be accessed
ERROR_BAD_CONFIGURATION | Configuration data is corrupt
ERROR_INSTALL_UI_FAILURE | Could not initialize handler interface
ERROR_INSTALL_LOG_FAILURE | Could not open log file in requested mode
ERROR_INSTALL_LANGUAGE_UNSUPPORTED | No acceptable language could be found
ERROR_INSTALL_TRANSFORM_FAILURE | Database transform failed to merge
ERROR_INSTALL_PACKAGE_REJECTED | This installation is forbidden by system policy. Contact your system administrator.
ERROR_PATCH_PACKAGE_OPEN_FAILED | Patch package could not be opened
ERROR_PATCH_PACKAGE_INVALID | Patch package invalid.
ERROR_PATCH_PACKAGE_UNSUPPORTED | Patch package unsupported
ERROR_INSTALL_REMOTE_DISALLOWED | Installation from a Terminal Services client session not permitted for current user.
ERROR_PATCH_TARGET_NOT_FOUND | The installer cannot install the upgrade patch because the program being upgraded may be missing or the upgrade patch updates a different version of the program. Verify that the program to be upgraded exists on your computer and that you have the correct upgrade patch. This error is not returned by Windows Installer version 1.0.


Displayed Error Messages

The installer only displays an error message dialog box for the following returned error codes. For any other returned error codes, the caller of the function can safely assume that the error message has been displayed to the user if the UILevel property is greater than INSTALLUILEVEL_NONE.

Error code | Error
ERROR_INSTALL_SUSPEND | The install was suspended.
ERROR_INSTALL_USEREXIT | The user exited the install.
ERROR_INSTALL_FAILURE | Install failed.
ERROR_INSTALL_PLATFORM_UNSUPPORTED | A Windows Installer earlier than version Windows Installer version 1.5 was called to install a 64-bit package.


INSTALLUI_HANDLER

The INSTALLUI_HANDLER function prototype defines a callback function that the installer calls for progress notification and error messages. For more information on the usage of this function prototype, a sample code snippet is available in Handling Progress Messages Using MsiSetExternalUI.

INT(WINAPI*INSTALLUI_HANDLER)(
  LPVOID pvContext,   // application context
  UINT iMessageType,  // message type
  LPCTSTR szMessage   // message
);

Parameters

pvContext
Pointer to an application context passed to the MsiSetExternalUI function. This parameter can be used for error checking.
iMessageType
Specifies a combination of one message box style, one message box icon type, one default button, and one installation message type. This parameter must be one of the following.
Message box StylesFlag | Meaning
MB_ABORTRETRYIGNORE | The message box contains the Abort, Retry, and Ignore buttons.
MB_OK | The message box contains the OK button. This is the default.
MB_OKCANCEL | The message box contains the OK and Cancel buttons.
MB_RETRYCANCEL | The message box contains the Retry and Cancel buttons.
MB_YESNO | The message box contains the Yes and No buttons.
MB_YESNOCANCEL | The message box contains the Yes, No, and Cancel buttons.

Message box IconTypesFlag | Meaning
MB_ICONEXCLAMATION,
MB_ICONWARNING 		An exclamation point appears in the message box.
MB_ICONINFORMATION,
MB_ICONASTERISK 		The information sign appears in the message box.
MB_ICONQUESTION | A question mark appears in the message box.
MB_ICONSTOP,
MB_ICONERROR,
MB_ICONHAND 		A stop sign appears in the message box.

Default ButtonsFlag | Meaning
MB_DEFBUTTON1 | The first button is the default button.
MB_DEFBUTTON2 | The second button is the default button.
MB_DEFBUTTON3 | The third button is the default button.
MB_DEFBUTTON4 | The fourth button is the default button.

Install message TypesFlag | Meaning
INSTALLMESSAGE_FATALEXIT | Premature termination
INSTALLMESSAGE_ERROR | Formatted error message
INSTALLMESSAGE_WARNING | Formatted warning message
INSTALLMESSAGE_USER | User request message.
INSTALLMESSAGE_INFO | Informative message for log
INSTALLMESSAGE_FILESINUSE | List of files currently in use that must be closed before being replaced
INSTALLMESSAGE_RESOLVESOURCE | Request to determine a valid source location
INSTALLMESSAGE_OUTOFDISKSPACE | Insufficient disk space message
INSTALLMESSAGE_ACTIONSTART | Start of action message. This message includes the action name and description.
INSTALLMESSAGE_ACTIONDATA | Formatted data associated with the individual action item.
INSTALLMESSAGE_PROGRESS | Progress gauge information. This message includes information on units so far and total number of units.
INSTALLMESSAGE_COMMONDATA | Formatted dialog information for user interface.
INSTALLMESSAGE_INITIALIZE | Sent prior to UI initialization, no string data
INSTALLMESSAGE_TERMINATE | Sent after UI termination, no string data
INSTALLMESSAGE_SHOWDIALOG | Sent prior to display of authored dialog or wizard

The following defaults should be used if any of the preceding messages are missing: MB_OK, no icon, and MB_DEFBUTTON1. There is no default installation message type; a message type is always specified.

szMessage
Specifies the message text.

Return Values

-1
An error was found in the message handler.
0
No action was taken.

The following return values map to the buttons specified by the message box style:

IDOK
IDCANCEL
IDABORT
IDRETRY
IDIGNORE
IDYES
IDNO

Remarks

For more information on returning values from an external user interface handler, see the Returning Values from an External User Interface Handler topic.

See Also

MsiSetExternalUI


MSIFILEHASHINFO

The MSIFILEHASHINFO structure contains the file hash information returned by MsiGetFileHash and used in the MsiFileHash table.

typedef struct _MSIFILEHASHINFO {
  ULONG dwFileHashInfoSize;
  ULONG dwData [ 4 ];
} MSIFILEHASHINFO, *PMSIFILEHASHINFO;

Members

dwFileHashInfoSize
Specifies the size, in bytes, of this data structure. Set this member to sizeof(MSIFILEHASHINFO) before calling the MsiGetFileHash function.
dwData
The entire 128-bit file hash is contained in four 32-bit fields. The first field corresponds to the HashPart1 column of the MsiHashFile table, the second field corresponds to the HashPart2 column, the third field corresponds to the HashPart3 column, and the fourth field corresponds to the HashPart4 column.

Remarks

The file hash entered into the fields of the MsiFileHash table must be obtained by calling MsiGetFileHash or the FileHash method. Do not use other methods to generate a file hash.

See Also

MsiGetFileHash, MsiFileHash table, Default File Versioning


Installer Database

The material in this section is primarily for developers who want to write tools that create new installer packages and who need detailed information about the installer's relational database. Complete installer packages are adopted by application developers as an efficient means to manage the installation of their applications. Knowledge of the installation database is also useful to application developers and administrators who want to modify existing installer packages and installation processes using custom actions. For general information on the Microsoft® Windows® Installer and component management technology, see About Windows Installer.

The installer database contains all the necessary information for the installation of an application. Therefore developers of tools for the creation of install packages and developers creating install packages without using such tools need to understand the installer database. The following topics cover the major areas of functionality of the installer database:

About the Installer Database

Using the Installer Database

Installer Database Reference


About the Installer Database

The Microsoft® Windows® Installer database consists of many interrelated tables that together comprise a relational database of the information necessary to install a group of applications. Because the database is relational, the tables are linked through the data in the primary and foreign key values. This provides an efficient method for changing the installation process and means that users can more easily customize a large application or group of applications. The database tables reflect the general layout of the entire group of applications, including:

  • Available features
  • Components
  • Relationship between features and components
  • Necessary registry settings
  • User interface for the application

To create an installation database, you must populate the tables with all the information about the applications and the installation process. Manually authoring all these tables becomes a large task even for a moderate size installation; therefore some third-party tools are available to assist with building the installer database. The following sections describe groups of related database tables.

Core Tables Group

File Tables Group

Registry Tables Group

System Tables Group

Locator Tables Group

Program Information Tables Group

Installation Procedure Tables Group

For a complete list of all tables in an installation database, see Database Tables.


Core Tables Group

For more information about the following diagram, see the entity relationship diagram legend.

The core group consists of tables describing the fundamental features and components of the application and the installer package. Developers of install packages should therefore consider how to populate these tables first because the organization of much of the database will become apparent from the content of this group.

  • The Feature table lists all features belonging to the application.
  • The Condition table contains the conditional expressions that determine whether or not a particular feature will be installed.
  • The FeatureComponents table describes which components belong to each feature.
  • The Component table lists all components belonging to the installation.
  • The Directory table lists the directories that are needed during the installation. Because each component must be associated with one and only one directory, the Component table is closely related to this table and has an external key to the Directory table.
  • The PublishComponent table lists the features and components that are published for use by other applications. Components and Features are the two types of feature advertisement.
  • The MsiAssembly table specifies Windows Installer settings for .NET Framework Common Language Runtime assemblies and Win32 assemblies.
  • The MsiAssemblyName table specifies the schema for the elements of a strong assembly cache name for a .NET Framework Common Language Runtime or Win32 assembly.
  • The Complus table contains information needed to install COM+ applications.
  • The IsolatedComponent table associates the component specified in the Component_Application column (commonly an .exe) with the component specified in the Component_Shared column (commonly a shared DLL).
  • The Upgrade table contains information required during major upgrades.


File Tables Group

For more information about this diagram, see the entity relationship diagram legend.

An installer package developer should consider populating the file table group of tables after breaking the application into components and features and after populating the core tables group. The file table group contains all of the files belonging to the installation and most of these files are listed in the File table. The Directory table is not shown in the figure but is closely related to the file table group. The Directory table gives the directory structure of the installation.

The file group of tables contains all of the tables that are related to files.

  • The File table lists files belonging to the installation. Files that are not listed in the File table include disk files, which are listed in Media table. Because every file belongs to a component, the File table has an external key into the Component table.
  • The RemoveFile table contains a list of files to be removed by the RemoveFiles action.
  • The Font table lists font files to be registered with the system.
  • The SelfReg table lists module files of the installation that are self-registered.
  • The Media table lists the source media and disks belonging to the installation.
  • The BindImage table lists files that are bound to DLLs imported by executables.
  • The MoveFile table specifies which files are moved during the installation.
  • The DuplicateFile table specifies which files are duplicated during the installation.
  • The IniFile table lists the .ini files and the information that the application needs to set in the file.
  • The RemoveIniFile table contains the information an application needs to delete from a .ini file.
  • The Environment table is used to set the values of environment variables and in Windows 95, the Environment table lists changes that will be made to the autoexec.bat file.
  • The Icon table provides icon information which is copied to a file as a part of product advertisement.
  • The FileSFPCatalog table associates specified files with the catalog files used by Windows File Protection on Windows Millennium Edition.
  • The SFPCatalog table contains the catalogs used by Windows Millennium Edition for Windows File Protection on Windows Millennium Edition.
  • The MsiFileHash table is used to store a 128-bit hash of a source file provided by the Windows Installer package.


Registry Tables Group

For more information about this diagram, see the entity relationship diagram legend.

The installer has specific tables for the different types of registry entries. When populating the registry tables group it is important to try to minimize the number of entries put into the Registry table and maximize the use of the other, specific, registry tables. This is because the installer cannot distinguish between different types of registry entries in the Registry table and cannot use the internal logic necessary to take full advantage of all of the installer features, such as advertising. Authoring COM and shell-related registry entries in this way also provides a more logical organization and can help minimize erroneous registration of COM server information.

The figure shows the registry entry group of tables as well as the Component table, Feature table, and File table. Although the latter are not directly involved with populating the registry, they are included in the figure because they are essential to the logic of the registry entry group.

The registry entry group contain the following tables of specific registry entries.

  • The Extension table contains all of the filename extensions your application uses along with their associated features and components.
  • The Verb table associates command-verb information with the file extensions listed in the Extension table. This provides an indirect link between the Verb and Feature table that is needed for feature advertisement.
  • The TypeLib table provides information that the installer places in the registry for the registration of type libraries. Type library entries are not written at the time of advertisement. The installer writes the type library entries at the time the components associated with the library are installed.
  • The MIME table associates a MIME context type with a CLSID or a file extension. This provides a path between the MIME and Feature Table that is needed for feature advertisement.
  • The SelfReg table provides information needed to self-register modules. Self-registration is provided by the installer only for backward compatibility and it is not recommended as a method for populating the registry, however if there are any modules in your application that must register themselves, use the SelfReg table.
  • The Class table is used to register Class IDs and other information for COM objects. This table contains COM server-related information that must be generated as a part of the product advertisement.
  • The ProgId table associates program IDs with class IDs.
  • The AppId table is used to register common security and configuration settings for DCOM objects.
  • The Environment table is used to set the values of environment variables, and in Windows NT/Windows 2000 the Environment table writes to registry as well.
  • The Registry table holds any other information that the application needs to put into the system registry. This would include default settings, user information or data, or COM registration not supported by the above tables.
  • The RemoveRegistry table contains the registry information the application needs to delete from the system registry at installation time.


System Tables Group

The tables of the system tables group track the tables and columns of the installation database.

  • The _Tables table tracks all the tables in the database. This includes tables that you may have created for your own custom actions. Query this table to find out if a table exists.
  • The _Columns table tracks columns in the installation database. Temporary columns are currently not tracked by this table. Query this table to find out if a given column exists.
  • The _Streams table lists embedded OLE data streams.
  • The _Storages table lists embedded OLE data storages.
  • The _Validation table. The _Validation table tracks the types and allowed ranges of every column in the database. The _Validation table is used during the database validation process to ensure that all columns are accounted for and have the correct values. This table is not shipped with the installer database.


Locator Tables Group

The Locator Tables group is used to locate files and applications. To search for a file, first determine the file signature and then locate the file. The Locator tables are used to search the registry, installer configuration data, directory tree, or .ini files for the unique signature of a file. The file signature can then be checked in the Signature table to ascertain that a particular file is really the file being sought and not another file with the same name. If a record in a locator table does not contain a key into the Signature table, then the record refers to a directory and not a file.

The component controlling a file is found in the File table through the external key to the Component table. The installer resolves the location of a file through the Component table because every file belongs to one component. The location of a component is found through an external key in the Component table to the Directory table.

The location of an application is found by searching for files that make up the application. The installer also provides two tables for searching for previous versions of an application: the AppSearch table and the CCPSearch table.

The following tables make up the Locator tables group and are used to determine the file signature.

  • The RegLocator table holds the information needed to search for a file or directory in the registry.
  • The IniLocator table holds the information needed to search for a .ini file. The .ini file must be present in the default Microsoft® Windows® directory.
  • The CompLocator table holds the information needed to search for a file or a directory using the installer's configuration data.
  • The DrLocator table holds the information needed to search for a file or directory in the directory tree.
  • The AppSearch table contains the properties that must be set to the search result of a corresponding file signature.
  • The CCPSearch table contains the list of file signatures, at least one of which needs to be present on a user's computer for the Compliance Checking Program (CCP).


Program Information Tables Group

The Program Information Tables group contain important information that used throughout the installation.

  • The Property table provides a means to specify all of the properties of an installation.
  • The Binary table holds the binary data for items such as bitmaps, animations, and icons. The binary table is also used to store data for custom actions. This table can contain a bitmap for a billboard, the icon for your program, or the executable form of a custom action.
  • The Error table is used to look up error message formatting templates when processing errors with an error code set. This is for the usual case where there is no formatting template set. The installer has its own error processing mechanism. Errors are passed as records.
  • Shortcut table the shortcut table holds the information the application needs to create Shortcuts on the user's computer.
  • The ReserveCost table contains the disk space necessary for each component to work properly.


Installation Procedure Tables Group

The tables in the Installation Procedure group control tasks performed during the installation by standard actions and custom actions.

Some of the tables in this group control a high level action by providing a sequence of actions. Each of the following sequence tables controls a portion of a high level action.

  • InstallUISequence table
  • InstallExecuteSequence table
  • AdminUISequence table
  • AdminExecuteSequence table
  • AdvtUISequence table
  • AdvtExecuteSequence table

There may be situations in which an installation needs to do something that is not possible using only standard actions. To provide the greatest degree of flexibility, the installer provides setup authors the ability to create their own custom actions. If you have any custom actions, you should register them with the installer by populating the CustomAction Table.

The CustomAction table provides the means of integrating custom code and data into the installation process. The code that is executed can be a stream contained within the database, a recently installed file, or an existing executable.

The following tables extend the installer's capabilities to manipulate files and folders during the installation.

  • The RemoveFile table contains a list of files that are removed during the installation.
  • The RemoveIniFile table contains the information an application needs to remove from .ini files.
  • The RemoveRegistry table contains the information which is deleted from the system registry when the corresponding component is selected to be installed.
  • The CreateFolder table lists the folders that must be created during the installation. Although the installer creates folders as they are needed, these are removed as soon as they are empty. Folders list in the CreateFolder table are not deleted until the component is uninstalled.
  • The MoveFile table contains a list of files to be moved or copied from a specified source directory on the user's computer to a destination directory. It is not necessary to use the MoveFile table to describe the files associated with the components you are installing.

To set up necessary conditions that must be met to initiate the installation, populate the LaunchCondition table.

The LaunchCondition table contains a list of conditions, all of which must be satisfied for the action to succeed.


Using the Installer Database

The database enables the developer of an installation package to control the transfer of an application from a source to a target image. The layout of both the source and target images of the application are specified in the Directory table and the actions that install the application are specified in six sequence tables:

  • InstallUISequence table
  • InstallExecuteSequence table
  • AdminUISequence table
  • AdminExecuteSequence table
  • AdvtUISequence table
  • AdvtExecuteSequence table

The following sections describe how to use the Installer Database:

  • Using the Directory Table
  • Using a Sequence Table
  • Obtaining a Database Handle
  • Committing Databases
  • Importing and Exporting
  • Merging Databases
  • Working with Queries
  • Working with Records
  • Working with Folder Locations
  • Specifying the Order of Self Registration
  • Conditioning Actions to Run During Removal
  • Calling Database Functions from Programs
  • Conditional Statement Syntax
  • Column Definition Format
  • How do I determine whether a column is a primary key or external key?


Using the Directory Table

The Directory table specifies the layout of an installation. When the directories are resolved during the CostFinalize action, the keys in the Directory table become properties set to directory paths. Note that the installer sets a number of standard properties to system folder paths. See the Property Reference for a list of the properties that are set to system folders.

The following is an example of a Directory table.

Directory | Directory_Parent | DefaultDir
TARGETDIR |  | SourceDir
EXEDIR | TARGETDIR | App
DLLDIR | EXEDIR | Bin
DesktopFolder | TARGETDIR | Desktop

Each row of the Directory table indicates a directory both at the source and the target. For example, assume the installation package resides at \\applications\source\. Because the Directory_Parent field of the first row is Null, this record indicates the root directories for both the source and the target. For the source, the value of this directory is given by the DefaultDir field. The SourceDir property defaults to the location of the installation package. Thus, unless the SourceDir property is overridden, the root source directory is \\applications\source\.

The Directory field of the first record indicates the location of the root target directory. In this case, the value of the TARGETDIR property indicates this directory. Typically, the value of the TARGETDIR property is set at the command line or through a user interface. In this case, assume the TARGETDIR property is set to C:\Program Files\Target\.

For the second record, the Directory_Parent field is not Null. Therefore, this record indicates a non-root directory for both the source and the target. For a non-root source directory, the source directory indicated by the record described in the Directory_Parent field is the parent directory. For the second record, the Directory_Parent field is TARGETDIR. As shown earlier, the source directory indicated by the TARGETDIR record resolved to \\applications\source\. Thus, the source directory indicated by the second record is \\applications\source\App\.

A similar process works for the target directory. The value of the parent directory for the target directory described in the second record is the target directory resolved by the Directory_Parent field. Again, the Directory_Parent field contains the value TARGETDIR. This indicates the first record that resolves to a target directory of C:\Program Files\Target\. The Directory field contains an author-defined property called EXEDIR. If this property is set, then its value gives the full path of the directory. Thus, if this property is set to C:\Data\Common\, the value of the target directory indicated by the second record is C:\Data\Common\. If it is not set, the target directory takes the name given by the DefaultDir field. In this case, the target directory is C:\Program Files\Target\App\.

The same process works for the third record. If EXEDIR and DLLDIR are not set, the target directory is C:\Program Files\Target\App\Bin, and the source directory is \\applications\source\App\Bin\.

The fourth record uses the DesktopFolder property. If the location of the user's desktop is C:\Winnt\Profiles\User\Desktop\, the target directory resolves to C:\Winnt\Profiles\User\Desktop\. The source directory resolves to \\applications\source\Desktop\.

There are two additional syntax features that can be used in the DefaultDir column of the Directory table. For a non-root source directory, a period (.) entered in the DefaultDir column indicates that the directory should be located in its parent directory without a subdirectory. To specify different source and target directory paths, separate the target and source paths in the DefaultDir column with a colon as follows: [targetpath]:[sourcepath]. These features can be used together to add levels to either the source or target paths for a single directory. See the following example of a Directory table.

Directory | Directory_Parent | DefaultDir
TARGETDIR |  | SourceDir
MyAppDir | TARGETDIR | MyApp
BinDir | MyAppDir | Bin
Binx86Dir | BinDir | .:x86
BinAlphaDir | BinDir | .:Alpha

The source and target paths resolve for the MyAppDir, BinDir, Binx86Dir, and BinAlphaDir rows as follows.

Record | Target paths | Source paths
MyAppDir: | [TARGETDIR]MyApp | [SourceDir]MyApp
BinDir: | [TARGETDIR]MyApp\Bin | [SourceDir]MyApp\Bin
Binx86Dir: | [TARGETDIR]MyApp\Bin | [SourceDir]MyApp\Bin\x86
BinAlphaDir: | [TARGETDIR]MyApp\Bin | [SourceDir]MyApp\Bin\Alpha

Note The Alpha platform is not supported by Windows Installer version 1.1.


Using a Sequence Table

The authoring of the sequence tables is an essential part of developing an installer package because these tables specify the order of execution for the standard actions that control the installation process and display the user interface dialog boxes.

There are three modes of installation and two types of sequence tables for each mode. The three separate installation modes currently supported by the installer are:

  • Simple Installation
  • Administrative Installation
  • Advertisement Installation

The sequence tables each have three fields: Action, Condition, and Sequence. The Action field names either a standard or custom action or a user defined dialog box or sequence the installer executes. The Condition field allows the author to specify a logical expression that controls whether an action or user-defined dialog is executed or displayed. If the Condition field is blank or contains an expression that evaluates to True, the action or dialog is executed or displayed. The action or dialog is skipped if the expression evaluates to False. The Sequence field specifies the order of execution of each action or user-defined dialog in the table.

Each of these installation modes processes the user interface sequence tables and the execute sequence tables. The user interface sequence tables are only processed if the installer was initialized with the user interface display level set to Reduced or Full. See the MsiSetInternalUI reference for more information about user interface display levels.

The user interface sequence tables typically contains standard actions related to collecting system information that are displayed to the user through the user interface. The user interface is displayed by recording the foreign keys to the names of dialog boxes in the dialog table in the Action field of the user interface sequence table. The user then has the opportunity to modify or accept the system information and begin the installation, which occurs when the execute sequence table is processed.

During a simple installation, the INSTALL top-level action is executed which in turn processes the InstallUISequence table and the InstallExecuteSequence table.

An Administrative Installation is typically initiated by a network administrator to assign and install applications for individual users and groups of users. During this type of installation, the ADMIN top-level action is executed which processes the AdminUISequence table and the AdminExecuteSequence table.

To advertise an application or feature, the installer must be initiated with the ADVERTISE. During this type of installation the AdvtExecuteSequence table is processed.

When authoring any sequence table, it is good practice to use the sequence number for standard actions from the suggested sequences in the topics below. For standard actions which have no standard position in the sequence table such as ForceReboot, ValidateProductID, and InstallExecute, use a sequence number that is a multiple of ten to identify the action as a standard action. For custom actions, use a sequence number that is not a multiple of ten to differentiate it from standard actions in the sequence table.

For suggested action sequences for each sequence table, see the following topics:

  • Suggested InstallUISequence
  • Suggested InstallExecuteSequence
  • Suggested AdminUISequence
  • Suggested AdminExecuteSequence
  • Suggested AdvtUISequence
  • Suggested AdvtExecuteSequence

For a detailed description of sequence tables and how standard actions are executed, see the sequence table detailed example.


Sequence Table Detailed Example

Here is an example of a sequence table.

Action | Condition | Sequence
LaunchConditions |  |
AppSearch |  | 200
CCPSearch | CCP_TEST | 300
CCPDialog | NOT_CCP_SUCCESS | 400
MyCustomConfig | NOT Installed | 500
CostInitialize |  | 600
FileCost |  | 700
CostFinalize |  | 800
InstallDialog | NOT Installed | 900
MaintenanceDialog | Installed AND NOT Resume | 1000
ActionDialog |  | 1100
RegisterProduct |  | 1200
InstallValidate |  | 1300
InstallFiles |  | 1400
MyCustomAction | $MyComponent > 2 | 1500
InstallFinalize |  | 1600

The following actions in this sequence table are defined by the installer and are examples of standard actions:

LaunchConditions
AppSearch
CCPSearch
CostInitialize
FileCost
CostFinalize
RegisterProduct
InstallFiles
InstallFinalize

The following actions were defined by the table's author and are examples of custom actions and must be listed in the CustomAction table:

MyCustomConfig
MyCustomAction

The remaining entries in the Action field are foreign keys into the Dialog table. They specify the names of dialog boxes that will displayed if the condition field evaluates to True.

CCPDialog
InstallDialog
MaintenanceDialog
ActionDialog

The Condition column causes the installer to skip the action if the property or expression in this field is False. The Installed property and the RESUME property are example of properties that are set by the installer. The Installed property is set to true if the product is already installed and the RESUME property is set if resuming a suspended installation. The CCP_TEST and the NOT_CCP_SUCCESS properties are examples of properties that can be set at the command line by the user installing the application.

All actions run in sequence with the following conditional steps:

  • The CPPSearch is run only if CCP_TEST is set.
  • CCPDialog is run only if NOT_CCP_SUCCESS is set.
  • MaintenanceDialog is run only if this product is already installed and if this is not an installation that is being resume after being suspended.
  • MyCustomAction is run only if the expression in the Condition column is True. The expression $MyComponent > 2 refers to the action state of the component called MyComponent. This condition indicates that MyCustomAction should only be run if MyComponent is set to be installed. For more information on Action states and Selection states, see the FeatureRequestState property, the Feature table, and the InstallFiles action.

See also

Using Properties, Conditional Statement Syntax


Suggested InstallUISequence

Action | Condition | Sequence
FatalErrorDlg |  | -3
UserExitDlg |  | -2
ExitDlg |  | -1
LaunchConditions |  | 100
PrepareDlg |  | 140
AppSearch |  | 400
CCPSearch | NOT Installed | 500
RMCCPSearch | NOT Installed | 600
CostInitialize |  | 800
FileCost |  | 900
CostFinalize |  | 1000
WelcomeDlg | NOT Installed | 1230
ResumeDlg | Installed AND (RESUME OR Preselected) | 1240
MaintenanceWelcomeDlg | Installed AND NOT RESUME AND NOT Preselected | 1250
ProgressDlg |  | 1280
ExecuteAction |  | 1300


Suggested InstallExecuteSequence

Action | Condition | Sequence
LaunchConditions |  | 100
AppSearch |  | 400
CCPSearch | NOT Installed | 500
RMCCPSearch | NOT Installed | 600
ValidateProductID |  | 700
CostInitialize |  | 800
FileCost |  | 900
CostFinalize |  | 1000
SetODBCFolders |  | 1100
InstallValidate |  | 1400
InstallInitialize |  | 1500
AllocateRegistrySpace | NOT Installed | 1550
ProcessComponents |  | 1600
UnpublishComponents |  | 1700
UnpublishFeatures |  | 1800
StopServices | VersionNT | 1900
DeleteServices | VersionNT | 2000
UnregisterComPlus |  | 2100
SelfUnregModules |  | 2200
UnregisterTypeLibraries |  | 2300
RemoveODBC |  | 2400
UnregisterFonts |  | 2500
RemoveRegistryValues |  | 2600
UnregisterClassInfo |  | 2700
UnregisterExtensionInfo |  | 2800
UnregisterProgIdInfo |  | 2900
UnregisterMIMEInfo |  | 3000
RemoveIniValues |  | 3100
RemoveShortcuts |  | 3200
RemoveEnvironmentStrings |  | 3300
RemoveDuplicateFiles |  | 3400
RemoveFiles |  | 3500
RemoveFolders |  | 3600
CreateFolders |  | 3700
MoveFiles |  | 3800
InstallFiles |  | 4000
PatchFiles |  | 4090
DuplicateFiles |  | 4210
BindImage |  | 4300
CreateShortcuts |  | 4500
RegisterClassInfo |  | 4600
RegisterExtensionInfo |  | 4700
RegisterProgIdInfo |  | 4800
RegisterMIMEInfo |  | 4900
WriteRegistryValues |  | 5000
WriteIniValues |  | 5100
WriteEnvironmentStrings |  | 5200
RegisterFonts |  | 5300
InstallODBC |  | 5400
RegisterTypeLibraries |  | 5500
SelfRegModules |  | 5600
RegisterComPlus |  | 5700
InstallServices | VersionNT | 5800
StartServices | VersionNT | 5900
RegisterUser |  | 6000
RegisterProduct |  | 6100
PublishComponents |  | 6200
PublishFeatures |  | 6300
PublishProduct |  | 6400
InstallFinalize |  | 6600


Suggested AdminUISequence

Action | Condition | Sequence
FatalErrorDlg |  | -3
UserExitDlg |  | -2
ExitDlg |  | -1
PrepareDlg |  | 140
CostInitialize |  | 800
FileCost |  | 900
CostFinalize |  | 1000
AdminWelcomeDlg |  | 1230
ProgressDlg |  | 1280
ExecuteAction |  | 1300


Suggested AdminExecuteSequence

Action | Condition | Sequence
CostInitialize |  | 800
FileCost |  | 900
CostFinalize |  | 1000
InstallValidate |  | 1400
InstallInitialize |  | 1500
InstallAdminPackage |  | 3900
InstallFiles |  | 4000
InstallFinalize |  | 6600


Suggested AdvtUISequence

Do not author the AdvtUISequence table. The installer does not use this table. The AdvtUISequence table should not exist in the installation database or it should be left empty. The name of the application to be advertised should be passed in to the installer during initialization.


Suggested AdvtExecuteSequence

Action | Condition | Sequence
CostInitialize |  | 800
CostFinalize |  | 1000
InstallValidate |  | 1400
InstallInitialize |  | 1500
CreateShortcuts |  | 4500
RegisterClassInfo |  | 4600
RegisterExtensionInfo |  | 4700
RegisterProgIdInfo |  | 4800
RegisterMIMEInfo |  | 4900
PublishComponents |  | 6200
PublishFeatures |  | 6300
PublishProduct |  | 6400
InstallFinalize |  | 6600


Obtaining a Database Handle

Before working with a database you must first obtain a handle to it.

To access information about an installer database

  1. Obtain a handle to the database in one of two ways:
    • If an installation is in progress, get a handle to the active database by calling the MsiGetActiveDatabase function.
    • If an installation is not in progress, open any specified database by calling the MsiOpenDatabase function.
  2. Once the database is open, you can call functions to obtain information about the database or to manipulate the database.
    • Create a view object and specify a SQL query of the open database by calling the MsiDatabaseOpenView function.
    • Obtain a record that contains all primary keys of a specified table in the open database by calling the MsiDatabaseGetPrimaryKeys function.
    • Check the current state of an open database by calling the MsiGetDatabaseState function. With the MsiGetDatabaseState function, you can determine the read/write status for a database or if the handle is valid.


Committing Databases

Changes made to the installation database are not written to the database until you call MsiDatabaseCommit.

To ensure changes made in a database are finalized

  1. Check to see whether a table will be written when you call MsiDatabaseCommit by calling MsiDatabaseIsTablePersistent.
  2. Call the MsiDatabaseCommit function to finalize changes to the database.

Changes made in a database are accumulated and are not reflected in the actual database until you call MsiDatabaseCommit. Temporary columns or rows are not committed to the database. When a database is closed, all changes made since the last MsiDatabaseCommit are automatically rolled back.


Importing and Exporting

You can use the installer to import a text archive into an active database as well as to export a database file to a text archive. This can be useful for text-based source control systems.

To import a text archive into an active database, call the MsiDatabaseImport function.

To export a database file to a text archive, call the MsiDatabaseExport function.


Merging Databases

You can use the installer to add the information in one database into another database by performing a merge. Merges and Transforms operate on an entire database, and a merge combines two databases into one. Merges are useful to development teams because they allow the installation database of large application to be divided into smaller parts and then recombined into the complete installation database later.

To merge several component databases into a single complete database

  1. Develop the partial component databases separately.
  2. Merge each component database into the main product database by calling the MsiDatabaseMerge function.


Naming Custom Tables, Properties and Actions

Starting with Windows Installer version 1.5, all new native Windows Installer properties, actions, and tables are given names prefixed by Msi. This prefix is not case sensitive, for example MsiNewInternalTable.

A package author can ensure that the names of any custom tables, properties, or actions in his package will not conflict with future versions of the Windows Installer by not using new names beginning with Msi. Because the prefix is not case sensitive, authors should avoid all cases of the msi prefix. To prevent conflict with versions earlier than Windows Installer version 1.5, authors should use their own prefix created for use with their custom properties, actions, and tables.

For more information, see Table Names.


Working with Queries

Because the installer uses a relational database, there are functions for making Structured Query Language (SQL) queries to the database. The following procedure describes how to use SQL to query a database.

To query a database with SQL

  1. Open the view object, with the appropriate SQL statement, by calling the MsiDatabaseOpenView function.

    A view object is the logical table created by applying a query to a set of tables. SQL queries must adhere to the SQL syntax provided by the installer. This SQL statement can contain parameter markers that are not specified until the view object runs.

  2. Run the view object by calling the MsiViewExecute function.
  3. Retrieve the next record from a view object by calling the MsiViewFetch function.
  4. Modify the view object by calling the MsiViewModify function.

    You can also validate data with MsiViewModify by passing the appropriate flags. If MsiViewModify returns ERROR_INVALID_DATA from a validation request, the underlying data is corrupt.

  5. Obtain detailed error information on the view object by calling the MsiViewGetError function.
  6. Close the view object by calling the MsiViewClose function.

See also Examples of Database Queries Using SQL and Script.


Examples of Database Queries Using SQL and Script

An example of using script-driven database queries is provided in the Microsoft® Windows® Installer Software Development Kit (SDK) as the utility WiRunSQL.vbs. This utility handles database queries using the Windows Installer version of SQL described in the section SQL Syntax.

Delete a record from a table

The following command line deletes the record having the primary key RED from the Feature table of the Test.msi database.

Cscript WiRunSQL.vbs Test.msi "DELETE FROM Feature WHERE Feature.Feature='RED'"

Add a table to a database

The following command line adds the Directory table to the Test.msi database.

CScript WiRunSQL.vbs Test.msi "CREATE TABLE `Directory` (`Directory` CHAR(72) NOT NULL, `Directory_Parent` CHAR(72), `DefaultDir` CHAR(255) NOT NULL LOCALIZABLE PRIMARY KEY `Directory`)"

Remove a table from a database

The following command line removes the Feature table from the Test.msi database.

Cscript WiRunSQL.vbs Test.msi "DROP TABLE Feature"

Add a new column to a table

The following command line adds the Test column to the CustomAction table of the Test.msi database.

CScript WiRunSQL.vbs Test.msi "ALTER TABLE `CustomAction` ADD `Test` INTEGER"

Insert a new record into a table

The following command line inserts a new record into the Feature table of the Test.msi database.

Cscript WiRunSQL.vbs Test.msi "INSERT INTO Feature (Feature.Feature,Feature.Feature_Parent,Feature.Title,Feature.Description,Feature.Display,Feature.Level,Feature.Directory_,Feature.Attributes) VALUES ('Tennis','Sport','Tennis','Tournament',25,3,'SPORTDIR',2)"

This inserts the following record into the Feature table of Test.msi.

Feature Table

Feature | Feature_Parent | Title | Description | Display | Level | Directory_ | Attributes
Tennis | Sport | Tennis | Tournament | 25 | 3 | SPORTDIR | 2

Modify an existing record in a table

The following command line changes the existing value in the Title field to "Performances." The updated record has "Arts" as its primary key and is in the Feature table of the Test.msi database

Cscript WiRunSQL.vbs Test.msi "UPDATE Feature SET Feature.Title='Performances' WHERE Feature.Feature='Arts'"

Select a group of records

The following command line selects the name and type of all controls that belong to the ErrorDialog in the Test.msi database.

CScript WiRunSQL.vbs Test.msi "SELECT `Control`, `Type` FROM `Control` WHERE `Dialog_`='ErrorDialog' "

Hold a table in memory

The following command line locks the Component table of the Test.msi database in memory.

CScript WiRunSQL.vbs Test.msi "ALTER TABLE `Component` HOLD"

Free a table in memory

The following command line frees the Component table of the Test.msi database from memory.

CScript WiRunSQL.vbs Test.msi "ALTER TABLE `Component` FREE"


Working with Records

The installer supplies functions that manipulate the records in an installation database. These functions can be used in conjunction with the functions described in Working with Queries to make actual changes in a database.

The following functions create or remove records:

  • To create a new record for a database, call the MsiCreateRecord function.
  • To clear data from a record, set each field to NULL by calling the MsiRecordClearData function.

The following functions fill specified fields of records:

  • To set a record to an integer, call the MsiRecordSetInteger function.
  • To set a record to a string, call the MsiRecordSetString function.
  • To insert an entire file into a stream field, call the MsiRecordSetStream function.

The following functions read values from specified fields of records:

  • To read an integer value from a field, call the MsiRecordGetInteger function.
  • To retrieve a string value, call the MsiRecordGetString function.
  • To obtain a stream, call the MsiRecordReadStream function.
  • To determine if a particular field of a record is NULL, call the MsiRecordIsNull function.

The following functions are informational record functions:

  • To get the number of fields a record contains, call the MsiRecordGetFieldCount function.
  • To get the size of a field, call the MsiRecordDataSize function. The return value of MsiRecordDataSize is sensitive to the field type.


Working with Folder Locations

Use the following functions to find the source or target of a specified folder in the Directory table:

  • Obtain the path of the specified source folder by calling the MsiGetSourcePath function.
  • Obtain the path of the specified target folder by calling the MsiGetTargetPath function.
  • Change the target location for a folder with the MsiSetTargetPath function.


Specifying the Order of Self Registration

Note that you cannot specify the order in which the installer registers or unregisters self-registering DLLs by using the SelfRegModules and SelfUnRegModules actions. These actions register all the modules listed in the SelfReg table. The installer does not self-register .exe files.

To specify the order in which the installer registers or unregisters modules, you must use two custom actions for each module. One custom action for DllRegisterServer and a second for DllUnregisterServer. These custom actions must then be authored in the InstallExecuteSequence table at the point in the sequence wherever the DLL is to be registered or unregistered.

The following example illustrates how to author the database to schedule the self-registration of a DLL at a particular point in the action sequence.

File Table (partial)

File | Component_ | FileName | Sequence
mydll | myComponent | mydll.dll | 13

Component Table (partial)

Component | ComponentId | Directory_ | KeyPath
myComponent | {a GUID} | myFolder | mydll

Directory Table

Directory | Directory_Parent | DefaultDir
TARGETDIR |  | SourceDir
myFolder | TARGETDIR | myFolder|My Folder

CustomAction Table

Action | Type | Source | Target
mydllREG | 3170 | myFolder | "[SystemFolder]msiexec" /y "[#mydll]"
mydllUNREG | 3170 | myFolder | "[SystemFolder]msiexec" /z "[#mydll]"

InstallExecuteSequence Table (partial)

Action | Condition | Sequence
SelfUnregModules |  | 2200
mydllUNREG | $myComponent=2 | 2201
RemoveFiles |  | 3500
InstallFiles |  | 4000
SelfRegModules |  | 6500
mydllREG | $myComponent>2 | 6501


Conditioning Actions to Run During Removal

There are two ways to author the installation database such that an action is only called when the package in uninstalled:

  • If the action is sequenced after the InstallValidate action in the InstallExecuteSequence table, the package author may specify REMOVE ="ALL" for the action in the Condition column. Note that the REMOVE property is not guaranteed to be set to "ALL" during an uninstall before the installer executes the InstallValidate action.
  • If the action is sequenced after the CostFinalize action and any actions that could change the feature state, such as MigrateFeatureStates action, the action can be conditioned on the state of a particular feature or component. See Conditional Statement Syntax. Use this option to call an action during the removal of a particular feature or component, which may occur outside of the complete removal of the application.

Note that the Installed property can be used in conditional expressions to determine whether a product is installed per-computer or for the current user. To determine whether the product is installed for a different user, check the ProductState property.


Calling Database Functions from Programs

Before calling any of the following Database Functions from a program, such as a custom action or an automation process, the installer must first run the CostInitialize action, FileCost action, and CostFinalize action.

MsiGetComponentState
MsiGetFeatureCost
MsiGetFeatureState
MsiGetFeatureValidStates
MsiGetTargetPath
MsiSetComponentState
MsiSetFeatureState
MsiSetTargetPath
MsiSetInstallLevel
MsiVerifyDiskSpace

Before calling MsiGetFeatureInfo from a program, such as a custom action or an automation process, the installer must first run the CostInitialize action.

Before calling MsiSetFeatureAttributes from a program, the installer must first run the CostInitialize action. The installer then runs the CostFinalize action after MsiSetFeatureAttributes.

Example

The following example illustrates the order in which functions actions must be called when using MsiGetTargetPath in a program.

MSIHANDLE hInstall;
TCHAR szBuf[MAX_PATH];
DWORD cch = sizeof(szBuf);
MsiOpenPackage("PathToPackage....", &hInstall);
MsiDoAction(hInstall, "CostInitialize");
MsiDoAction(hInstall, "FileCost");
MsiDoAction(hInstall, "CostFinalize");
MsiGetTargetPath(hInstall, "FolderName", szBuf,&cch);


Conditional Statement Syntax

This section describes the syntax of conditional statements used by the MsiEvaluateCondition function and the action sequence tables.

Summary of Conditional Statement Syntax

This table and bullets summarizes the syntax to use in conditional expressions. More information is given in following sections.

Item | Syntax
value | symbol | literal | integer
comparison-operator | < | > | <= | >= | = | <>
term | value | value comparison-operator value | ( expression )|
Boolean-factor | term | NOT term
Boolean-term | Boolean-factor | Boolean-factor AND term
expression | Boolean-term | Boolean-term OR expression
symbol | property | %environment-variable | $component-action | ?component-state | &feature-action | !feature-state

  • Symbol names and values are case-sensitive.
  • Environment variable names are not case-sensitive.
  • Literal text must be enclosed between quotation marks ("text").
  • Non-existent property values are treated as empty strings.
  • Floating point numeric values are not supported.
  • Operators and precedence are the same as in the BASIC and SQL languages.
  • Arithmetic operators are not supported.
  • Parentheses can be used to override operator precedence.
  • Operators are not case-sensitive.
  • For string comparisons, a tilde "~" prefixed to the operator performs a comparison that is not case-sensitive.
  • Comparison of an integer with a string or property value that cannot be converted to an integer is always msiEvaluateConditionFalse, except for the comparison operator "<>", which returns msiEvaluateConditionTrue.

Access Prefixes

The following table shows the prefixes to use to access various system and installer information for use in conditional expressions.

Symbol type | Prefix | Value
Installer property | (none) | Value of property (Property table).
Environment variable | % | Value of environment variable.
Component table key | $ | Action state of the component.
Component table key | ? | Installed state of the component.
Feature table key | & | Action state of the feature.
Feature table key | ! | Installed state of the feature.

Logical Operators

The following table shows the logical operators in conditional expressions, in high to low precedence order.

Operator | Meaning
Not | Prefix unary operator; inverts state of following term.
And | TRUE if both terms are TRUE.
Or | TRUE if either or both terms are TRUE.
Xor | TRUE if either but not both terms are TRUE.
Eqv | TRUE if both terms are TRUE or both terms are FALSE.
Imp | TRUE if left term is FALSE or right term is TRUE.

Comparative Operators

The following table shows the comparison operators used in conditional expressions. These comparison operators can only occur between two values.

Operator | Meaning
= | TRUE if left value is equal to right value.
<> | TRUE if left value is not equal to right value.
> | TRUE if left value is greater than right value.
>= | TRUE if left value is greater than or equal to right value.
< | TRUE if left value is less than right value.
<= | TRUE if left value is less than or equal to right value.

Substring Operators

The following table shows the substring operators used in conditional expressions. Substring operators can occur between two string values.

Operator | Meaning
>< | TRUE if left string contains the right string.
<< | TRUE if left string starts with the right string.
>> | TRUE if left string ends with the right string.

Bitwise Numeric Operators

The following table shows the bitwise numeric operators in conditional expressions. These operators can occur between two integer values.

Operator | Meaning
>< | Bitwise AND, TRUE if the left and right integers have any bits in common.
<< | True if the high 16-bits of the left integer are equal to the right integer.
>> | True if the low 16-bits of the left integer are equal to the right integer.

Feature and Component State Values

The following table shows where it is valid to use the feature and component operator symbols.

Operator <state> | Where this syntax is valid.
$component-action | Only in the sequence tables after the CostFinalize action.
&feature-action | Only in the sequence tables after the CostFinalize action.
!feature-state | Only in the sequence tables after the CostFinalize action.
?component-state | In the Condition table, in the Condition column of the Component table, and in the sequence tables, after the CostFinalize action.

The following table shows the feature and component state values used in conditional expressions. These states are not set until MsiSetInstallLevel is called, either directly or by the CostFinalize action.

State | Value | Meaning
INSTALLSTATE_UNKNOWN | -1 | No action to be taken on feature or component.
INSTALLSTATE_ADVERTISED | 1 | Advertised feature. This state is not available for components.
INSTALLSTATE_ABSENT | 2 | Feature or component not present.
INSTALLSTATE_LOCAL | 3 | Feature or component on local computer.
INSTALLSTATE_SOURCE | 4 | Feature or component run from source.

For example, the conditional expression "&MyFeature=3" evaluates to true only if MyFeature is changing from its current state to the state of being installed on the local computer, INSTALLSTATE_LOCAL.

See also

Using Properties in Conditional Statements


Column Definition Format

MsiViewGetColumnInfo and the ColumnInfo Property of the View object use the following format to describe database column definitions. Each column is described by a string in the corresponding record field returned by the function or property. The definition string consists of a single letter representing the data type followed by the width of the column (in characters when applicable, bytes otherwise). A width of zero designates an unbounded width (for example, long text fields and streams). An uppercase letter indicates that NULL values are allowed in the column.

Column descriptor | Definition string
s? | String, variable length (?=1-255)
s0 | String, variable length
i2 | Short integer
i4 | Long integer
v0 | Binary Stream
g? | Temporary string (?=0-255)
j? | Temporary integer (?=0,1,2,4)

The strings used to describe columns have the following relationship to the SQL query strings used by CREATE and ALTER. For more information, see SQL Syntax.

Returned value | SQL syntax
s0 | LONGCHAR
l0 | LONGCHAR LOCALIZABLE
s # | CHAR(#)
s # | CHARACTER(#)
l # | CHAR(#) LOCALIZABLE
l # | CHARACTER(#) LOCALIZABLE
i2 | SHORT
i2 | INT
i2 | INTEGER
i4 | LONG
v0 | OBJECT

If the letter is not capitalized, the SQL statement should be appended with NOT NULL for example:

Returned value | SQL syntax
s0 | LONGCHAR NOT NULL

The Windows Installer does not internally limit the length of columns to the value specified by the column definition format. If the data entered into a field exceeds the specified column length, the package fails to pass package validation. To pass validation in this case, either the data or the database schema must be changed. The only means to change the column length of a standard table is by exporting the table using MsiDatabaseExport, editing the exported .idt file, and then importing the table using MsiDatabaseImport. Authors cannot change the column data types, nullability, or localization attributes of any columns in standard tables. Authors can create custom tables with columns having any column attributes.

When using MsiDatabaseMerge to merge a reference database into a target database, the column names, number of primary keys, and column data types must match. MsiDatabaseMerge ignores the localization and column length attributes. If a column in the reference database has a length that is 0 or greater than the that column's length in the target database, MsiDatabaseMerge increases the column length in the target database to the length in the reference database. Note that merge modules never change the schema of the target database. This includes never changing the length of table columns.


How do I determine whether a column is a primary key or external key?

You can determine whether a particular column is a primary key or external key of the table by consulting the table's reference page. A list of links to the reference pages of all the installation database tables is located under Database Tables. Each of these reference pages identifies columns which are a primary key or an external key.

Database columns that are external keys take the name of the primary key column with an added underscore character. For example, an external key to the File column of the File table is always named File_.

To view entity relationship diagrams that illustrate table relationships, see Core Tables Group, File Tables Group, Registry Tables Group, System Tables Group, or User Interface Schema.


Installer Database Reference

To add installer functionality to your application, you can use the Microsoft® Windows® Installer database tables and the installer database functions. The topics in this section provide reference material for each of the database functions and database tables.

To view a list of all the installation database tables, see Database Tables.

To view a list of the functions that are used to work with information in installation databases, see Database Functions.


Database Functions

The material in this section is intended for developers who are writing their own setup programs and developers who want to learn more about the installer database tables. For general information on the installer, see About Windows Installer.

You can use the installer access functions to access the database and the installation process. These functions should only be used by custom installation actions and authoring tools. Some of the installer access functions require SQL query strings for querying the database. Queries must adhere to the installer SQL syntax.

This topic lists the installer database access functions by category.

General Database Access Functions

Function Name | Brief Description of Function
MsiDatabaseCommit | Commits changes to a database.
MsiDatabaseGetPrimaryKeys | Returns the names of all the primary key columns.
MsiDatabaseIsTablePersistent | Returns an enumeration describing the state of a table.
MsiDatabaseOpenView | Prepares a database query and creates a view object.
MsiGetActiveDatabase | Returns the active database for the installation.
MsiViewGetColumnInfo | Returns column names or definitions.
MsiOpenDatabase | Opens a database file for data access.
MsiViewClose | Releases the result set for an executed view.
MsiViewExecute | Executes the view query and supplies required parameters.
MsiViewFetch | Fetches the next sequential record from the view.
MsiViewGetError | Returns the error that occurred in the MsiViewModify function.
MsiViewModify | Updates a fetched record.

Database Management Functions

Function Name | Brief Description of Function
MsiCreateTransformSummaryInfo | Creates summary information for an existing transform.
MsiDatabaseApplyTransform | Applies a transform to a database.
MsiDatabaseExport | Exports a table from an open database to a text archive file.
MsiDatabaseGenerateTransform | Generates a transform file of differences between two databases.
MsiDatabaseImport | Imports an installer text archive table into an open database.
MsiDatabaseMerge | Merges two databases together.
MsiGetDatabaseState | Returns the state of the database.

Record Processing Functions

Function Name | Brief Description of Function
MsiCreateRecord | Creates new record object with specified number of fields.
MsiFormatRecord | Formats record field data and properties using a format string.
MsiRecordClearData | Sets all fields in a record to NULL.
MsiRecordDataSize | Returns the length of a record field.
MsiRecordGetFieldCount | Returns the number of fields in a record.
MsiRecordGetInteger | Returns the integer value from a record field.
MsiRecordGetString | Returns the string value of a record field.
MsiRecordIsNull | Reports whether a record field is NULL.
MsiRecordReadStream | Reads bytes from a record stream field into a buffer.
MsiRecordSetInteger | Sets a record field to an integer field.
MsiRecordSetStream | Sets a record stream field from a file.
MsiRecordSetString | Copies a string into the designated field.

Summary Information Property Functions

Function Name | Brief Description of Function
MsiGetSummaryInformation | Obtains handle to summary information stream of installer database.
MsiSummaryInfoGetProperty | Gets a single property from the summary information.
MsiSummaryInfoGetPropertyCount | Returns number of properties in the summary information stream.
MsiSummaryInfoPersist | Writes changed summary information back to summary information stream.
MsiSummaryInfoSetProperty | Sets a single summary information property.

Installer State Access Functions

Function Name | Brief Description of Function
MsiGetLanguage | Returns the numeric language of the current installation.
MsiGetLastErrorRecord | Returns error record last returned for the calling process.
MsiGetMode | Returns one of the Boolean internal installation states.
MsiGetProperty | Gets the value of an installer property.
MsiSetProperty | Sets the value of an installation property.
MsiSetMode | Sets an internal engine Boolean state.

Installer Action Functions

Function Name | Brief Description of Function
MsiDoAction | Executes built-in action, custom action, or user-interface wizard action.
MsiEvaluateCondition | Evaluates a conditional expression containing property names and values.
MsiProcessMessage | Sends an error record to the installer for processing.
MsiSequence | Executes an action sequence.

Installer Location Functions

Function Name | Brief Description of Function
MsiGetSourcePath | Returns the full source path for a folder in the Directory table.
MsiGetTargetPath | Returns the full target path for a folder in the Directory table.
MsiSetTargetPath | Sets the full target path for a folder in the Directory table.

Installer Selection Functions

Function Name | Brief Description of Function
MsiGetComponentState | Obtains the state of a component.
MsiGetFeatureCost | Returns the disk space required by a feature.
MsiGetFeatureState | Gets the state of a feature.
MsiGetFeatureValidStates | Returns a valid installation state.
MsiSetComponentState | Sets a component to the specified state.
MsiSetFeatureAttributes | Modifies the default attributes of a feature at run time.
MsiSetFeatureState | Sets a feature to a specified state.
MsiSetInstallLevel | Sets the installation level of a full product installation.
MsiVerifyDiskSpace | Checks for sufficient disk space.

User Interface Functions

Function Name | Brief Description of Function
MsiEnableUIPreview | Enables preview mode of the user interface.
MsiPreviewBillboard | Displays a billboard with the host control in the displayed dialog box.
MsiPreviewDialog | Displays a dialog box as modeless and inactive.

All functions support both ANSI and Unicode calls. To use these functions, include MsiQuery.h and link with Msi.lib.

Installation Functions

In addition to the database access functions listed above, you create an installation package for an application by using the installer functions listed in the Installer Function Reference section.


SQL Syntax

The SQL query strings are restricted to the following format.

To select a group of records.

SELECT [DISTINCT]{column-list} FROM {table-list} [WHERE {operation-list}] [ORDER BY {column-list}]

To delete records from a table.

DELETE FROM {table} [WHERE {operation-list}]

To modify existing records in a table.

UPDATE {table-list} SET {column}= {constant} [, {column}= {constant}][, ...] [WHERE {operation-list}]

Note that UPDATE queries only work on non-primary key columns.

To add records to a table.

INSERT INTO {table} ({column-list}) VALUES ({constant-list}) [TEMPORARY]

To add a table.

CREATE TABLE {table} ( {column} {column type}) [HOLD]

Note that column types must be specified for each column when adding a table. The possible substitutions for {column type} in the above are: CHAR [( {size} )] | CHARACTER [( {size} )] | LONGCHAR | SHORT | INT | INTEGER | LONG | OBJECT [NOT NULL] [TEMPORARY] [LOCALIZABLE] [, column...][, ...] PRIMARY KEY column [, column][, ...].

To remove a table.

DROP TABLE {table}

To add a column.

ALTER TABLE {table} ADD {column} {column type}

Note that the column type must be specified when adding a column. The possible substitutions for {column type} in the above are: CHAR [( {size} )] | CHARACTER [( {size} )] | LONGCHAR | SHORT | INT | INTEGER | LONG | OBJECT [NOT NULL] [TEMPORARY] [LOCALIZABLE] [HOLD].

To hold and free temporary tables.

ALTER TABLE {table name} HOLD

ALTER TABLE {table name} FREE

The user can use the commands HOLD and FREE to control the life span of a temporary table or a temporary column. The hold count on a table is incremented for every SQL HOLD operation on that table and decremented for every SQL FREE operation on the table. When the last hold count is released on a table, all temporary columns become inaccessible. If all columns are temporary, the table becomes inaccessible.

Optional parameters are shown enclosed in brackets [ ]. When several choices are listed, the optional parameters are separated by a vertical bar.

A {constant} is either a string or an integer. A string must be enclosed in single quote marks 'example'. A {constant-list} is a comma-delimited list of one or more constants.

The LOCALIZABLE option sets a column attribute that indicates the column needs to be localized.

A {column} is a columnar reference to a value in a field of a table.

A {marker} is a parameter reference to a value supplied by a record submitted with the query. It is represented in the SQL statement by a question mark ?. For information regarding the use of parameters, see either the MsiViewExecute function or the Execute method.

Note that the Windows Installer SQL syntax does not support the escaping of single-quotes (ASCII value 39) in a string literal. You may instead fetch or create the record, set the field with the StringData or IntegerData property, and then call the Modify method. Alternatively, you can create a record and use the parameter markers (?) described in Execute method. You may also do this using the Database Functions MsiViewExecute, MsiRecordSetInteger, and MsiRecordSetString.

A WHERE {operation-list} clause is optional and is a grouping of operations to be used to filter the selection. The operations must be of the following types:

  • {column} = {column}
  • {column} = | <> | > | < | >= | <= {constant}
  • {column} = | <> | > | < | >= | <= {marker}
  • {column} is null
  • {column} is not null

For string values, only the = or <> operations are possible. Object value comparisons are limited to IS NULL and IS NOT NULL.

Individual operations can be grouped by AND or OR operators. Ordering can be imposed by use of parentheses ( ).

The ORDER BY clause is optional and causes an initial delay during sorting. Ordering by strings will group identical strings together, but it will not alphabetize the strings.

The DISTINCT clause is optional and does not repeat identical records in the returned result set.

A {table-list} is a comma-delimited list of one or more table names referred to as {table} in the join.

A {column-list} is a comma-delimited list of one or more table columns referred to as {column} selected. Ambiguous columns may be further qualified as {tablename.column}. An asterisk may be used as a column-list in a SELECT query to represent all columns in the referenced tables. When referencing fields by column position, select the columns by name instead of using the asterisk. An asterisk cannot be used as a column-list in an INSERT INTO query.

To escape table names and column names that clash with SQL keywords, enclose the name between two grave accent marks `` (ASCII value 96). If a column name must be escaped and is qualified as {tablename.column}, then the table and the column must be escaped individually as {`tablename`.`column`}. It is recommended that all table names and column names be escaped in this fashion to avoid clashes with reserved words and gain significant performance.

Table names are limited to 31 characters. See Table Names. Table and column names are case-sensitive. SQL keywords are not case-sensitive.

Only inner joins are supported and are specified by a comparison of columns from different tables. Circular joins are not supported. A circular join is a SQL query that links three or more tables together into a circuit. For example, the following is a circular join:

WHERE Table1.Field1=Table2.Field1 AND Table2.Field2=Table3.Field1 AND Table3.Field2=Table1.Field2.

Columns that are part of the primary key(s) for a table must be defined first in priority order, followed by any non-primary key columns. Persistent columns must be defined before temporary columns. The sort sequence of a text column is undefined; however, identical text values always group together.

Note that when adding or creating a column, you must specify the column type.

Tables may not contain more than one column of type 'object'.

The maximum size that can be explicitly specified for a string column in a SQL query is 255. A string column of infinite length is represented as having size 0. See Column Definition Format.

To execute any SQL statement, a view must be created. However, a view that does not create a result set, such as CREATE TABLE, or INSERT INTO, cannot be used with MsiViewModify or the Modify Method to update tables though the view.

Note that you cannot fetch a record containing binary data from one database and then use that record to insert the data into a completely different database. To move binary data from one database to another, you should export the data to a file and then import it into the new database via a query and the MsiRecordSetStream. This ensures that each database has its own copy of the binary data.

See also Examples of Database Queries Using SQL and Script.


MsiCreateRecord

The MsiCreateRecord function creates a new record object with the specified number of fields. This function returns a handle that should be closed using MsiCloseHandle.

MSIHANDLE MsiCreateRecord(
  unsigned int cParams  // the number of data fields
);

Parameters

cParams
[in] Specifies the number of fields the record will have. The maximum number of fields in a record is limited to 65535.

Return Values

If the function succeeds, the return value is handle to a new record object.

If the function fails, the return value is NULL.

Remarks

Field 0 of the record object created by the MsiCreateRecord function is used for format strings and operation codes and is not included in the count specified by cParams. All fields are initialized to NULL.

Note that it is recommended to use variables of type PMSIHANDLE because the installer closes PMSIHANDLE objects as they go out of scope, whereas you must close MSIHANDLE objects by calling MsiCloseHandle.

For example, if you use code like this:

MSIHANDLE hRec = MsiCreateRecord(3);

Change it to:

PMSIHANDLE hRec = MsiCreateRecord(3);

Requirements

Windows NT/2000: Requires Windows NT 4.0 SP3 or later. Available as a redistributable.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in Msiquery.h.
Library: Use Msi.lib.

See Also

Database Functions, Record Processing Functions


MsiCreateTransformSummaryInfo

The MsiCreateTransformSummaryInfo function creates summary information of an existing transform to include validation and error conditions. Execution of this function sets the error record, accessible via MsiGetLastErrorRecord

UINT MsiCreateTransformSummaryInfo(
  MSIHANDLE hDatabase,          // database handle
  MSIHANDLE hDatabaseReference, // reference database without changes
  LPCTSTR szTransformFile,      // name of generated transform file
  int iErrorConditions,         // conditions treated as errors when
                                //  transform applied
  int iValidation               // properties to be validated when
                                //  transform applied
);

Parameters

hDatabase
[in] Handle to the database that contains the new database Summary Information.
hDatabaseReference
[in] Handle to the database that contains the original Summary Information.
szTransformFile
[in] The name of the transform to which the Summary Information is added.
iErrorConditions
[in] The error conditions that should be suppressed when the transform is applied. Choose one or more of the following values:
Error condition | Value | Meaning
none | 0x00000000 | None of the following conditions.
MSITRANSFORM_ERROR_
ADDEXISTINGROW 		0x00000001 Adding a row that already exists.
MSITRANSFORM_ERROR_
DELMISSINGROW 		0x00000002 Deleting a row that doesn't exist.
MSITRANSFORM_ERROR_
ADDEXISTINGTABLE 		0x00000004 Adding a table that already exists.
MSITRANSFORM_ERROR_
DELMISSINGTABLE 		0x00000008 Deleting a table that doesn't exist.
MSITRANSFORM_ERROR_
UPDATEMISSINGROW 		0x00000010 Updating a row that doesn't exist.
MSITRANSFORM_ERROR_
CHANGECODEPAGE 		0x00000020 Transform and database code pages do not match and neither code page is neutral.

iValidation
[in] Specifies those properties to be validated to verify the transform can be applied to the database. This parameter can be one or more of the following values.
Validation flag | Value | Meaning
none | 0x00000000 | Validate no properties.
MSITRANSFORM_
VALIDATE_LANGUAGE 		0x00000001 Default language must match base database.
MSITRANSFORM_
VALIDATE_PRODUCT 		0x00000002 Product must match base database.

Validate product version flags.
Validation flag Value Meaning
MSITRANSFORM_VALIDATE_
MAJORVERSION 		0x00000008 Check major version only.
MSITRANSFORM_VALIDATE_
MINORVERSION 		0x00000010 Check major and minor versions only.
MSITRANSFORM_VALIDATE_
UPDATEVERSION 		0x00000020 Check major, minor, and update versions.

Product version relationship flags. In the following table the "Installed Version" is the version of the package being transformed and the "Base Version" is the version of the package used to create the transform.
Validation flag Value Meaning
MSITRANSFORM_VALIDATE_
NEWLESSBASEVERSION 		0x00000040 Installed version < base version.
MSITRANSFORM_VALIDATE_
NEWLESSEQUALBASEVERSION 		0x00000080 Installed version <= base version.
MSITRANSFORM_VALIDATE_
NEWEQUALBASEVERSION 		0x00000100 Installed version = base version.
MSITRANSFORM_VALIDATE_
NEWGREATEREQUALBASEVERSION 		0x00000200 Installed version >= base version.
MSITRANSFORM_VALIDATE_
NEWGREATERBASEVERSION 		0x00000400 Installed version > base version.

Upgrade code validation flags.
Validation flag Value Meaning
MSITRANSFORM_VALIDATE_
UPGRADECODE 		0x00000800 UpgradeCode must match base database.

Return Values

ERROR_INVALID_HANDLE
An invalid or inactive handle was supplied.
ERROR_INVALID_PARAMETER
An invalid parameter was passed to the function.
ERROR_OPEN_FAILED
The transform storage file could not be opened.
ERROR_SUCCESS
The function succeeded.
ERROR_INSTALL_PACKAGE_INVALID
Reference to an invalid Windows Installer package.

Remarks

To create a summary information stream for a transform, the ProductCode and ProductVersion properties must be defined in the Property tables of both the base and reference databases. If MSITRANSFORM_VALIDATE_UPGRADECODE is used, the UpgradeCode property must also be defined in both databases. If these conditions are not met MsiCreateTransformSummaryInfo returns ERROR_INSTALL_PACKAGE_INVALID.

Because the list delimiter for transforms, sources and patches is a semicolon, this character should not be used for filenames or paths.

This function cannot be called from custom actions. A call to this function from a custom action causes the function to fail.

See Transforms.

Requirements

Windows NT/2000: Requires Windows NT 4.0 SP3 or later. Available as a redistributable.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in Msiquery.h.
Library: Use Msi.lib.
Unicode: Implemented as Unicode and ANSI versions on all platforms.


MsiDatabaseApplyTransform

The MsiDatabaseApplyTransform function applies a transform to a database.

UINT MsiDatabaseApplyTransform(
  MSIHANDLE hDatabase,     // database handle
  LPCTSTR szTransformFile, // name of transform file
  int iErrorConditions     // error conditions to be suppressed
);

Parameters

hDatabase
[in] Handle to database to transform.
szTransformFile
[in] Specifies the name of the transform file to apply.
iErrorConditions
[in] Error conditions that should be suppressed. This parameter is a bit field that can contain the following bits.
Error condition | Value | Meaning
MSITRANSFORM_ERROR_ADDEXISTINGROW | 0x0001 | Adding a row that already exists.
MSITRANSFORM_ERROR_DELMISSINGROW | 0x0002 | Deleting a row that doesn't exist.
MSITRANSFORM_ERROR_ADDEXISTINGTABLE | 0x0004 | Adding a table that already exists.
MSITRANSFORM_ERROR_DELMISSINGTABLE | 0x0008 | Deleting a table that doesn't exist.
MSITRANSFORM_ERROR_UPDATEMISSINGROW | 0x0010 | Updating a row that doesn't exist.
MSITRANSFORM_ERROR_CHANGECODEPAGE | 0x0020 | Transform and database code pages do not match and neither has a neutral code page.
MSITRANSFORM_ERROR_VIEWTRANSFORM | 0x0100 | Create the temporary _TransformView table.

Return Values

ERROR_INVALID_HANDLE
An invalid or inactive handle was supplied.
ERROR_INVALID_PARAMETER
An invalid parameter was passed to the function.
ERROR_INSTALL_TRANSFORM_FAILURE
The transform could not be applied.
ERROR_OPEN_FAILED
The transform storage file could not be opened.
ERROR_SUCCESS
The function succeeded.

Remarks

The MsiDatabaseApplyTransform function delays transforming tables until it is necessary. Any tables to be added or dropped are processed immediately. However, changes to the existing table are delayed until the table is loaded or the database is committed.

An error occurs if MsiDatabaseApplyTransform is called when tables have already been loaded and saved to storage.

Because the list delimiter for transforms, sources and patches is a semicolon, this character should not be used for filenames or paths.

This function cannot be called from custom actions. A call to this function from a custom action causes the function to fail.

See Transforms.

Requirements

Windows NT/2000: Requires Windows NT 4.0 SP3 or later. Available as a redistributable.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in Msiquery.h.
Library: Use Msi.lib.
Unicode: Implemented as Unicode and ANSI versions on all platforms.

See Also

Database Management Functions


MsiDatabaseCommit

The MsiDatabaseCommit function commits changes to a database.

UINT MsiDatabaseCommit(
  MSIHANDLE hDatabase    // database handle
);

Parameters

hDatabase
[in] Handle to the database.

Return Values

ERROR_FUNCTION_FAILED
The function failed.
ERROR_INVALID_HANDLE
An invalid or inactive handle was supplied.
ERROR_INVALID_HANDLE_STATE
The handle is in an invalid state.
ERROR_SUCCESS
The function succeeded.

Remarks

The MsiDatabaseCommit function finalizes the persistent form of the database. All persistent data is then written to the writable database. No temporary columns or rows are written. The MsiDatabaseCommit function has no effect on a database that is opened as read-only. You can call this function multiple times to save the current state of tables loaded into memory. When the database is finally closed, any changes made after the database is committed are rolled back. This function is normally called prior to shutdown when all database changes have been finalized.

Requirements

Windows NT/2000: Requires Windows NT 4.0 SP3 or later. Available as a redistributable.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in Msiquery.h.
Library: Use Msi.lib.

See Also

General Database Access Functions


MsiDatabaseExport

The MsiDatabaseExport function exports an installer table from an open database to a text archive file.

UINT MsiDatabaseExport(
  MSIHANDLE hDatabase,    // database handle
  LPCTSTR szTableName,    // name of table to export
  LPCTSTR szFolderPath,   // folder containing archive files
  LPCTSTR szFileName      // name of exported table archive file
);

Parameters

hDatabase
[in] Handle to the database.
szTableName
[in] Specifies the name of the table to export.
szFolderPath
[in] Specifies the name of the folder that contains archive files.
szFileName
[in] Specifies the name of the exported table archive file.

Return Values

ERROR_BAD_PATHNAME
An invalid path was passed to the function.
ERROR_FUNCTION_FAILED
The function failed.
ERROR_INVALID_HANDLE
An invalid or inactive handle was supplied.
ERROR_INVALID_PARAMETER
An invalid parameter was passed to the function.
ERROR_SUCCESS
The function succeeded.

Remarks

If a table contains streams, MsiDatabaseExport exports each stream to a separate file.

See MsiDatabaseImport.

This function cannot be called from custom actions. A call to this function from a custom action causes the function to fail.

Requirements

Windows NT/2000: Requires Windows NT 4.0 SP3 or later. Available as a redistributable.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in Msiquery.h.
Library: Use Msi.lib.
Unicode: Implemented as Unicode and ANSI versions on all platforms.

See Also

Database Management Functions


MsiDatabaseGenerateTransform

The MsiDatabaseGenerateTransform function generates a transform file of differences between two databases. A transform is a way of recording changes to a database without altering the original database.

UINT MsiDatabaseGenerateTransform(
  MSIHANDLE hDatabase,          // database handle
  MSIHANDLE hDatabaseReference, // base database to reference changes
  LPCTSTR szTransformFile,      // name of generated transform file
  int iReserved1,               // this must be set to 0
  int iReserved2                // this must be set to 0
);

Parameters

hDatabase
[in] Handle to the database that includes the changes.
hDatabaseReference
[in] Handle to the database that does not include the changes.
szTransformFile
[in] The name of the generated transform file. This is optional.
iReserved1
[in] This is a reserved argument and must be set to 0.
iReserved2
[in] This is a reserved argument and must be set to 0.

Return Values

ERROR_NO_DATA
The two databases are identical and no transform file was generated.
ERROR_CREATE_FAILED
The storage for the transform file could not be created.
ERROR_INSTALL_TRANSFORM_FAILURE
The transform could not be generated.
ERROR_INVALID_HANDLE
An invalid or inactive handle was supplied.
ERROR_INVALID_PARAMETER
An invalid parameter was passed to the function.
ERROR_SUCCESS
The function succeeded.
NOERROR
If szTransformFile is NULL, then this is returned if differences are found.

Remarks

To generate a difference file between two databases, use the MsiDatabaseGenerateTransform function. A transform contains information regarding insertion and deletion of columns and rows. The validation flags are stored in the summary information stream of the transform file.

For tables that exist in both databases, the only difference between the two schemas that is allowed is the addition of columns to the end of the reference table. You cannot add primary key columns to a table or change the order or names or column definitions of the existing columns as defined in the base table. In other words, if neither table contains data and columns are removed from the reference table, the resulting table is identical to the base table.

Because the list delimiter for transforms, sources and patches is a semicolon, this character should not be used for filenames or paths.

This function does not generate a Summary Information stream. Use MsiCreateTransformSummaryInfo to create the stream for an existing transform.

If szTransformFile is NULL, you can test whether two databases are identical without creating a transform. If the databases are identical, ERROR_NO_DATA is returned, NOERROR is returned if differences are found.

This function cannot be called from custom actions. A call to this function from a custom action causes the function to fail.

Requirements

Windows NT/2000: Requires Windows NT 4.0 SP3 or later. Available as a redistributable.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in Msiquery.h.
Library: Use Msi.lib.
Unicode: Implemented as Unicode and ANSI versions on all platforms.

See Also

Database Management Functions, Transforms


MsiDatabaseGetPrimaryKeys

The MsiDatabaseGetPrimaryKeys function returns a record containing the names of all the primary key columns for a specified table. This function returns a handle that should be closed using MsiCloseHandle.

UINT MsiDatabaseGetPrimaryKeys(
  MSIHANDLE hDatabase,   // database handle
  LPCTSTR szTableName,   // name of table
  MSIHANDLE *phRecord    // handle for record
);

Parameters

hDatabase
[in] Handle to the database. See Obtaining a Database Handle.
szTableName
[in] Specifies the name of the table from which to obtain primary key names.
phRecord
[out] Pointer to the handle of the record that holds the primary key names.

Return Values

ERROR_INVALID_HANDLE
An invalid or inactive handle was supplied.
ERROR_INVALID_PARAMETER
An invalid parameter was passed to the function.
ERROR_INVALID_TABLE
An invalid table was passed to the function.
ERROR_SUCCESS
The function succeeded.

Remarks

The field count of the returned record is the count of primary key columns returned by the MsiDatabaseGetPrimaryKeys function. The returned record contains the table name in Field (0) and the column names that make up the primary key names in succeeding fields. These primary key names correspond to the column numbers for the fields.

This function cannot be used with the _Tables table or the _Columns table.

Note that it is recommended to use variables of type PMSIHANDLE because the installer closes PMSIHANDLE objects as they go out of scope, whereas you must close MSIHANDLE objects by calling MsiCloseHandle.

For example, if you use code like this:

MSIHANDLE hRec = MsiCreateRecord(3);

Change it to:

PMSIHANDLE hRec = MsiCreateRecord(3);

Requirements

Windows NT/2000: Requires Windows NT 4.0 SP3 or later. Available as a redistributable.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in Msiquery.h.
Library: Use Msi.lib.
Unicode: Implemented as Unicode and ANSI versions on all platforms.

See Also

General Database Access Functions


MsiDatabaseImport

The MsiDatabaseImport function imports an installer text archive table into an open database.

UINT MsiDatabaseImport(
  MSIHANDLE hDatabase,    // database handle
  LPCTSTR szFolderPath,   // folder containing archive files
  LPCTSTR szFileName      // table archive file to import
);

Parameters

hDatabase
[in] Handle to the database.
szFolderPath
[in] Specifies the path to the folder containing archive files.
szFileName
[in] Specifies the name of the file to import.

Return Values

ERROR_BAD_PATHNAME
An invalid path was passed to the function.
ERROR_FUNCTION_FAILED
The function failed.
ERROR_INVALID_HANDLE
An invalid or inactive handle was supplied.
ERROR_INVALID_PARAMETER
An invalid parameter was passed to the function.
ERROR_SUCCESS
The function succeeded.

Remarks

When you use the MsiDatabaseImport function to import a text archive table named _SummaryInformation into an installer database, you write the "05SummaryInformation" stream. This stream contains standard properties that can be viewed using Microsoft® Windows® Explorer and which are defined by COM. The rows of the table are written to the property stream as pairs of property ID numbers and corresponding data values. See Summary Information Stream Property Set. Date and time in _SummaryInformation are in the format: YYYY/MM/DD hh::mm::ss. For example, 1999/03/22 15:25:45. If the table contains binary streams, the name of the stream is in the data field, and the actual stream is retrieved from a file of that name in a subfolder with the same name as the table.

Text archive files that are exported from a database by MsiDatabaseExport are intended for use with version control systems, and are not intended to be used as a means of editing data. Use the database API functions and tools designed for that purpose. Note that control characters in text archive files are translated to avoid conflicts with file delimiters. If a text archive file contains non-ASCII data, it is stamped with the code page of the data, and can only be imported into a database of that exact code page, or into a neutral database. Neutral databases are set to the code page of the imported file. A database may be unconditionally set to a particular code page by importing a pseudo table named: _ForceCodepage. The format of such a file would be: Two blank lines, followed by a line containing the numeric code page, a tab delimiter and the exact string: _ForceCodepage

This function cannot be called from custom actions. A call to this function from a custom action causes the function to fail.

Requirements

Windows NT/2000: Requires Windows NT 4.0 SP3 or later. Available as a redistributable.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in Msiquery.h.
Library: Use Msi.lib.
Unicode: Implemented as Unicode and ANSI versions on all platforms.

See Also

Database Management Functions


MsiDatabaseIsTablePersistent

The MsiDatabaseIsTablePersistent function returns an enumeration describing the state of a particular table.

UINT MsiDatabaseIsTablePersistent(
  MSIHANDLE hDatabase,   // database handle
  LPCTSTR szTableName    // name of relevant table
);

Parameters

hDatabase
[in] Handle to the database to which the relevant table belongs.
szTableName
[in] Specifies the name of the relevant table.

Return Values

MSICONDITION_ERROR
An invalid handle or invalid parameter was passed to the function.
MSICONDITION_FALSE
The table is temporary.
MSICONDITION_NONE
The table is unknown.
MSICONDITION_TRUE
The table is persistent.

Requirements

Windows NT/2000: Requires Windows NT 4.0 SP3 or later. Available as a redistributable.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in Msiquery.h.
Library: Use Msi.lib.
Unicode: Implemented as Unicode and ANSI versions on all platforms.

See Also

General Database Access Functions


MsiDatabaseMerge

The MsiDatabaseMerge function merges two databases together, allowing duplicate rows. For information on attaching a merge module to an installation package, see Merge Modules.

UINT MsiDatabaseMerge(
  MSIHANDLE hDatabase,      // database handle
  MSIHANDLE hDatabaseMerge, // database to be merged into hDatabase
  LPCTSTR szTableName       // name of persistent table to receive rows
);

Parameters

hDatabase
[in] Handle to the base database.
hDatabaseMerge
[in] Handle to the database to merge into the base database.
szTableName
[in] Specifies the name of the table to receive merge conflict information.

Return Values

ERROR_FUNCTION_FAILED
Row merge conflicts were reported.
ERROR_INVALID_HANDLE
An invalid or inactive handle was supplied.
ERROR_INVALID_TABLE
An invalid table was supplied.
ERROR_SUCCESS
The function succeeded.
ERROR_DATATYPE_MISMATCH
Schema difference between the two databases.

Remarks

MsiDatabaseMerge does not copy over embedded cabinet files or embedded transforms from the reference database into the target database. Embedded data streams that are listed in the Binary table or Icon table are copied from the reference database to the target database. Storage embedded in the reference database are not copied to the target database.

The MsiDatabaseMerge function merges the data of two databases. These databases must have the same codepage. MsiDatabaseMerge fails if any tables or rows in the databases conflict. A conflict exists if the data in any row in the first database differs from the data in the corresponding row of the second database. Corresponding rows are in the same table of both databases and have the same primary key in both databases. The tables of non-conflicting databases must have the same number of primary keys, same number of columns, same column types, same column names, and the same data in rows with identical primary keys. Temporary columns however don't matter in the column count and corresponding tables can have a different number of temporary columns without creating conflict as long as the persistent columns match.

If the number, type, or name of columns in corresponding tables are different, the schema of the two databases are incompatible and the installer will stop processing tables and the merge fails. The installer checks that the two databases have the same schema before checking for row merge conflicts. If ERROR_DATATYPE_MISMATCH is returned, you are guaranteed that the databases have not been changed.

If the data in particular rows differ, this is a row merge conflict, the installer returns ERROR_FUNCTION_FAILED and creates a new table named szTableName. The first column of this table is the name of the table having the conflict. The second column gives the number of rows in the table having the conflict. The table reporting conflicts appears as follows.

Column | Type | Key | Nullable
Table | Text | Y | N
NumRowMergeConflicts | Integer |  | N

The following behavior only applies in Windows Installer version 1.1:

When merging a table, if a column containing string data has an identical type between the two databases with the sole exception of differing length limits, the table after the merge will have the larger of the two limits. If either of the columns has no limit (the limit is 0), then the column after the merge has no limit.

This function cannot be called from custom actions. A call to this function from a custom action causes the function to fail.

Requirements

Windows NT/2000: Requires Windows NT 4.0 SP3 or later. Available as a redistributable.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in Msiquery.h.
Library: Use Msi.lib.
Unicode: Implemented as Unicode and ANSI versions on all platforms.

See Also

Database Management Functions, Column Definition Format


MsiDatabaseOpenView

The MsiDatabaseOpenView function prepares a database query and creates a view object. This function returns a handle that should be closed using MsiCloseHandle.

UINT MsiDatabaseOpenView(
  MSIHANDLE hDatabase,   // database handle
  LPCTSTR szQuery,       // SQL query to be prepared
  MSIHANDLE *phView      // returned view if TRUE
);

Parameters

hDatabase
[in] Handle to the database to which you want to open a view object.
szQuery
[in] Specifies a SQL query string for querying the database. For correct syntax, see SQL Syntax.
phView
[out] Pointer to a handle for the returned view.

Return Values

ERROR_BAD_QUERY_SYNTAX
An invalid SQL query string was passed to the function.
ERROR_INVALID_HANDLE
An invalid or inactive handle was supplied.
ERROR_SUCCESS
The function succeeded, and the handle is to a view object.

Remarks

The MsiDatabaseOpenView function opens a view object for a database. You must open a view object for a database before performing any execution or fetching.

If an error occurs, you can call MsiGetLastErrorRecord for more information.

Note that it is recommended to use variables of type PMSIHANDLE because the installer closes PMSIHANDLE objects as they go out of scope, whereas you must close MSIHANDLE objects by calling MsiCloseHandle.

For example, if you use code like this:

MSIHANDLE hRec = MsiCreateRecord(3);

Change it to:

PMSIHANDLE hRec = MsiCreateRecord(3);

Requirements

Windows NT/2000: Requires Windows NT 4.0 SP3 or later. Available as a redistributable.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in Msiquery.h.
Library: Use Msi.lib.
Unicode: Implemented as Unicode and ANSI versions on all platforms.

See Also

General Database Access Functions


MsiDoAction

The MsiDoAction function executes a built-in action, custom action, or user-interface wizard action.

UINT MsiDoAction(
  MSIHANDLE hInstall,    // installer handle
  LPCTSTR szAction       // action
);

Parameters

hInstall
[in] Handle to the installation.
szAction
[in] Specifies the action to execute.

Return Values

ERROR_FUNCTION_FAILED
The function failed.
ERROR_FUNCTION_NOT_CALLED
The action was not found.
ERROR_INSTALL_FAILURE
The action failed.
ERROR_INSTALL_SUSPEND
The user suspended the installation.
ERROR_INSTALL_USEREXIT
The user canceled the action.
ERROR_INVALID_DATA
A failure occurred while calling the custom action.
ERROR_INVALID_HANDLE
An invalid or inactive handle was supplied.
ERROR_INVALID_HANDLE_STATE
The handle state was invalid.
ERROR_INVALID_PARAMETER
An invalid parameter was passed to the function.
ERROR_MORE_DATA
The action indicates that the remaining actions should be skipped.
ERROR_SUCCESS
The function succeeded.

Remarks

The MsiDoAction function executes the action that corresponds to the name supplied. If the name is not recognized by the installer as a built-in action or as a custom action in the CustomAction table, the name is passed to the user-interface handler object, which can invoke a function or a dialog box. If a NULL action name is supplied, the installer uses the upper-case value of the ACTION property as the action to perform. If no property value is defined, the default action is performed, defined as "INSTALL".

Actions that update the system, such as the InstallFiles and WriteRegistryValues actions, cannot be run by calling MsiDoAction. The exception to this rule is if MsiDoAction is called from a custom action that is scheduled in the InstallExecuteSequence table between the InstallInitialize and InstallFinalize actions. Actions that do not update the system, such as AppSearch or CostInitialize, can be called.

Requirements

Windows NT/2000: Requires Windows NT 4.0 SP3 or later. Available as a redistributable.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in Msiquery.h.
Library: Use Msi.lib.
Unicode: Implemented as Unicode and ANSI versions on all platforms.

See Also

Installer Action Functions


MsiEnableUIPreview

The MsiEnableUIPreview function enables preview mode of the user interface to facilitate authoring of user-interface dialog boxes. This function returns a handle that should be closed using MsiCloseHandle.

UINT MsiEnableUIPreview(
  MSIHANDLE hDatabase,  // database handle
  MSIHANDLE *phPreview  // returned handle for UI preview capability
);

Parameters

hDatabase
[in] Handle to the database.
phPreview
[out] Pointer to a returned handle for user-interface preview capability.

Return Values

ERROR_INVALID_HANDLE
An invalid or inactive handle was supplied.
ERROR_INVALID_PARAMETER
Bad parameter.
ERROR_OUTOFMEMORY
Out of memory.
ERROR_SUCCESS
The function succeeded.

Remarks

Note that it is recommended to use variables of type PMSIHANDLE because the installer closes PMSIHANDLE objects as they go out of scope, whereas you must close MSIHANDLE objects by calling MsiCloseHandle.

For example, if you use code like this:

MSIHANDLE hRec = MsiCreateRecord(3);

Change it to:

PMSIHANDLE hRec = MsiCreateRecord(3);

Requirements

Windows NT/2000: Requires Windows NT 4.0 SP3 or later. Available as a redistributable.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in Msiquery.h.
Library: Use Msi.lib.

See Also

User Interface Functions


MsiEvaluateCondition

The MsiEvaluateCondition function evaluates a conditional expression containing property names and values.

MSICONDITION MsiEvaluateCondition(
  MSIHANDLE hInstall,    // installer handle
  LPCTSTR szCondition    // conditional expression
);

Parameters

hInstall
[in] Handle to the installation.
szCondition
[in] Specifies the conditional expression. For the syntax of conditional expressions see Conditional Statement Syntax.

Return Values

MSICONDITION_ERROR
An invalid handle was passed to the function, or the conditional expression has a syntax error.
MSICONDITION_FALSE
An expression that evaluates to FALSE was passed to the function.
MSICONDITION_NONE
No expression was passed to the function.
MSICONDITION_TRUE
An expression that evaluates to TRUE was passed to the function.

Remarks

The following table shows the feature and component state values used by the MsiEvaluateCondition function. These states are not set until MsiSetInstallLevel is called, either directly or by the CostFinalize action. Therefore, state checking is generally only useful for conditional expressions in an action sequence table.

Value | Meaning
INSTALLSTATE_ABSENT - | Feature or component not present.
INSTALLSTATE_LOCAL - | Feature or component on local computer.
INSTALLSTATE_SOURCE - | Feature or component run from source.
(NULL value) - | No action to be taken on feature or component.

Requirements

Windows NT/2000: Requires Windows NT 4.0 SP3 or later. Available as a redistributable.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in Msiquery.h.
Library: Use Msi.lib.
Unicode: Implemented as Unicode and ANSI versions on all platforms.

See Also

Installer Action Functions


MsiFormatRecord

The MsiFormatRecord function formats record field data and properties using a format string.

UINT MsiFormatRecord(
  MSIHANDLE hInstall,    // installer handle
  MSIHANDLE hRecord,     // record to execute
  LPTSTR szResultBuf,    // buffer to return formatted string
  DWORD *pcchResultBuf   // in/out buffer character count
);

Parameters

hInstall
[in] Handle to the installation. This may be omitted, in which case only the record field parameters are processed and properties are not available for substitution.
hRecord
[in] Handle to the record to format. The template string must be stored in record field 0 followed by referenced data parameters.
szResultBuf
[in] Specifies the buffer to return the formatted string to.
pcchResultBuf
[out] Specifies the in/out character count. The count does not include the terminating null.

Return Values

ERROR_INVALID_HANDLE
An invalid or inactive handle was supplied.
ERROR_INVALID_PARAMETER
An invalid parameter was passed to the function.
ERROR_MORE_DATA
A buffer was too small to hold the entire value.
ERROR_SUCCESS
The function succeeded.

Remarks

The MsiFormatRecord function uses the following format process.

Parameters that are to be formatted are enclosed in square brackets [...]. The square brackets can be iterated because the substitutions are resolved from the inside out.

If a part of the string is enclosed in curly braces { } and contains no square brackets, it is left unchanged, including the curly braces.

If a part of the string is enclosed in curly braces { } and contains one or more property names, and if all the properties are found, the text (with the resolved substitutions) is displayed without the curly braces. If any of the properties is not found, all the text in the braces and the braces themselves are removed.

The following steps describe how to format strings using the MsiFormatRecord function:

To format strings using the MsiFormatRecord function

  1. The numeric parameters are substituted by replacing the marker with the value of the corresponding record field, with missing or null values producing no text.
  2. The resultant string is processed by replacing the non-record parameters with the corresponding values, described next.
    • If a substring of the form [propertyname] is encountered, it is replaced by the value of the property.
    • If a substring of the form [%environmentvariable] is found, the value of the environment variable is substituted.
    • If a substring of the form [#filekey] is found, it is replaced by the full path of the file, with the value filekey used as a key into the File table. The value of [#filekey] remains blank and is not replaced by a path until the installer runs the CostInitialize action, FileCost action, and CostFinalize action. The value of [#filekey] depends upon the installation state of the component to which the file belongs. If the component is being run from source, the value is the path to the source location of the file. If the component is being run locally, the value is the path to the target location of the file after installation. If the component is absent, the path is blank. For more information about checking the installation state of components see Checking the Installation of Features, Components, Files.
    • If a substring of the form [$componentkey] is found, it is replaced by the install directory of the component, with the value componentkey used as a key into the Component table. The value of [$componentkey] remains blank and is not replaced by a directory until the installer runs the CostInitialize action, FileCost action, and CostFinalize action. The value of [$componentkey] depends upon the installation state of the component. If the component is being run from source, the value is the source directory of the file. If the component is being run locally, the value is the target directory after installation. If the component is absent, the value is left blank. For more information about checking the installation state of components see Checking the Installation of Features, Components,
    • If a substring of the form [\c] is found, it is replaced by the character without any further processing. Only the first character after the backslash is kept; everything else is removed.

If ERROR_MORE_DATA is returned, the parameter which is a pointer gives the size of the buffer required to hold the string. If ERROR_SUCCESS is returned, it gives the number of characters written to the string buffer. Therefore you can get the size of the buffer by passing in an empty string (for example "") for the parameter that specifies the buffer. Do not attempt to determine the size of the buffer by passing in a Null (value=0).

Requirements

Windows NT/2000: Requires Windows NT 4.0 SP3 or later. Available as a redistributable.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in Msiquery.h.
Library: Use Msi.lib.
Unicode: Implemented as Unicode and ANSI versions on all platforms.


MsiGetActiveDatabase

The MsiGetActiveDatabase function returns the active database for the installation. This function returns a handle that should be closed using MsiCloseHandle.

MSIHANDLE MsiGetActiveDatabase(
  MSIHANDLE hInstall    // installer handle
);

Parameters

hInstall
[in] Handle to the installation passed to the custom action.

Return Values

If the function succeeds, it returns a handle to the database currently in use by the installer. If the function fails, the function returns zero, 0.

Remarks

The MsiGetActiveDatabase function accesses the database in use by the running the installation.

Note that it is recommended to use variables of type PMSIHANDLE because the installer closes PMSIHANDLE objects as they go out of scope, whereas you must close MSIHANDLE objects by calling MsiCloseHandle.

For example, if you use code like this:

MSIHANDLE hRec = MsiCreateRecord(3);

Change it to:

PMSIHANDLE hRec = MsiCreateRecord(3);

Requirements

Windows NT/2000: Requires Windows NT 4.0 SP3 or later. Available as a redistributable.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in Msiquery.h.
Library: Use Msi.lib.

See Also

General Database Access Functions


MsiGetComponentState

The MsiGetComponentState function obtains the state of a component.

UINT MsiGetComponentState(
  MSIHANDLE hInstall,         // installer handle
  LPCTSTR szComponent,        // component name within product
  INSTALLSTATE *piInstalled,  // returned current install state
  INSTALLSTATE *piAction      // action taken during install session
);

Parameters

hInstall
[in] Handle to the installation.
szComponent
[in] Specifies the component name within the product.
piInstalled
[out] Receives the current installed state. This parameter can be one of the following values.
Value | Meaning
INSTALLSTATE_NOTUSED | The component is disabled.
INSTALLSTATE_BADCONFIG | The configuration data is corrupt.
INSTALLSTATE_INCOMPLETE | The installation is suspended or in progress.
INSTALLSTATE_SOURCEABSENT | The component cannot run from the source because the source is unavailable.
INSTALLSTATE_MOREDATA | The buffer overflow is returned.
INSTALLSTATE_INVALIDARG | An invalid parameter was passed to the function.
INSTALLSTATE_UNKNOWN | An unrecognized product or feature name was passed to the function.
INSTALLSTATE_BROKEN | The component is broken.
INSTALLSTATE_REMOVED | The component is being removed. In action state and not settable.
INSTALLSTATE_ABSENT | The component is not installed.
INSTALLSTATE_LOCAL | The component is installed on the local drive.
INSTALLSTATE_SOURCE | The component will run from the source, CD-ROM, or network.
INSTALLSTATE_DEFAULT | The component will be installed in the default location: local or source.

piAction
[out] Receives the action taken during the installation. For return values, see piInstalled.

Return Values

ERROR_INVALID_HANDLE
An invalid or inactive handle was supplied.
ERROR_SUCCESS
The function succeeded.
ERROR_UNKNOWN_COMPONENT
An unknown component was requested.

Remarks

For more information, see Calling Database Functions From Programs.

Requirements

Windows NT/2000: Requires Windows NT 4.0 SP3 or later. Available as a redistributable.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in Msiquery.h.
Library: Use Msi.lib.
Unicode: Implemented as Unicode and ANSI versions on all platforms.

See Also

Installer Selection Functions


MsiGetDatabaseState

The MsiGetDatabaseState function returns the state of the database.

MSIDBSTATE MsiGetDatabaseState(
  MSIHANDLE hDatabase    // database handle
);

Parameters

hDatabase
[in] Handle to a database.

Return Values

MSIDBSTATE_READ
The database is opened as read-only; there can be no persistent changes.
MSIDBSTATE_ERROR
An invalid database handle was passed to the function.
MSIDBSTATE_WRITE
The database is readable and writable.

Remarks

The MsiGetDatabaseState function returns the update state of the database.

Requirements

Windows NT/2000: Requires Windows NT 4.0 SP3 or later. Available as a redistributable.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in Msiquery.h.
Library: Use Msi.lib.

See Also

Database Management Functions


MsiGetFeatureCost

The MsiGetFeatureCost function returns the disk space required by a feature and its selected children and parent features.

UINT MsiGetFeatureCost(
  MSIHANDLE hInstall,     // installer handle
  LPCTSTR szFeature,      // name of feature
  MSICOSTTREE iCostTree,  // portion of tree to cost
  INSTALLSTATE iState,    // requested state
  INT *piCost             // returned cost
);

Parameters

hInstall
[in] Handle to the installation.
szFeature
[in] Specifies the name of the feature.
iCostTree
[in] Specifies the value the function uses to determine disk space requirements. This parameter can be one of the following values.
Value | Meaning
MSICOSTTREE_CHILDREN | The children of the indicated feature are included in the cost.
MSICOSTTREE_PARENTS | The parent features of the indicated feature are included in the cost.
MSICOSTTREE_SELFONLY | The feature only is included in the cost.

iState
[in] Specifies the installation state. This parameter can be one of the following values.
Value | Meaning
INSTALLSTATE_UNKNOWN | The product or feature is unrecognized.
INSTALLSTATE_ABSENT | The product or feature is uninstalled.
INSTALLSTATE_LOCAL | The product or feature is installed on the local drive.
INSTALLSTATE_SOURCE | The product or feature is installed to run from source, CD, or network.
INSTALLSTATE_DEFAULT | The product or feature will be installed to use the default location: local or source.

piCost
[out] Receives the disk space requirements in units of 512 bytes.

Return Values

ERROR_FUNCTION_FAILED
The function failed.
ERROR_INVALID_HANDLE
An invalid or inactive handle was supplied.
ERROR_INVALID_HANDLE_STATE
An invalid handle state was supplied.
ERROR_INVALID_PARAMETER
An invalid parameter was passed to the function.
ERROR_SUCCESS
The function succeeded.
ERROR_UNKNOWN_FEATURE
An unknown feature was requested.

Remarks

See Calling Database Functions From Programs.

With the MsiGetFeatureCost function, the MSICOSTTREE_SELFONLY value indicates the total amount of disk space (in units of 512 bytes) required by the specified feature only. This returned value does not include the children or the parent features of the specified feature. This total cost is made up of the disk costs attributed to every component linked to the feature.

The MSICOSTTREE_CHILDREN value indicates the total amount of disk space (in units of 512 bytes) required by the specified feature and its children. For each feature, the total cost is made up of the disk costs attributed to every component linked to the feature.

The MSICOSTTREE_PARENTS value indicates the total amount of disk space (in units of 512 bytes) required by the specified feature and its parent features (up to the root of the Feature table). For each feature, the total cost is made up of the disk costs attributed to every component linked to the feature.

MsiGetFeatureCost is dependent upon several other functions to be successful. The following example demonstrates the order in which these functions must be called:

MSIHANDLE   hInstall;      //product handle, must be closed
int         iCost;         //cost returned by MsiGetFeatureCost

MsiOpenPackage("Path to package…",&hInstall);   //"Path to package" should be replaced with the full path to the package to be opened
MsiDoAction(hInstall,"CostInitialize");         //
MsiDoAction(hInstall,"FileCost");
MsiDoAction(hInstall,"CostFinalize");
MsiDoAction(hInstall,"InstallValidate");
MsiGetFeatureCost(hInstall,"FeatureName",MSICOSTTREE_SELFONLY,INSTALLSTATE_ABSENT,&iCost);
MsiCloseHandle(hInstall);                        //close the open product handle

The process to query the cost of features scheduled to be removed is slightly different:

MSIHANDLE   hInstall;      //product handle, must be closed
int         iCost;         //cost returned by MsiGetFeatureCost

MsiOpenPackage("Path to package…",&hInstall);                   //"Path to package" should be replaced with the full path to the package to be opened
MsiDoAction(hInstall,"CostInitialize");                          //
MsiDoAction(hInstall,"FileCost");
MsiDoAction(hInstall,"CostFinalize");
MsiSetFeatureState(hInstall,"FeatureName",INSTALLSTATE_ABSENT);  //set the feature's state to "not installed"
MsiDoAction(hInstall,"InstallValidate");
MsiGetFeatureCost(hInstall,"FeatureName",MSICOSTTREE_SELFONLY,INSTALLSTATE_ABSENT,&iCost);
MsiCloseHandle(hInstall);                                        //close the open product handle

Requirements

Windows NT/2000: Requires Windows NT 4.0 SP3 or later. Available as a redistributable.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in Msiquery.h.
Library: Use Msi.lib.
Unicode: Implemented as Unicode and ANSI versions on all platforms.

See Also

Installer Selection Functions


MsiGetFeatureState

The MsiGetFeatureState function gets the requested state of a feature.

UINT MsiGetFeatureState(
  MSIHANDLE hInstall,         // installer handle
  LPCTSTR szFeature,          // feature name within product
  INSTALLSTATE *piInstalled,  // returned current install state
  INSTALLSTATE *piAction      // action taken during install session
);

Parameters

hInstall
[in] Handle to the installation.
szFeature
[in] Specifies the feature name within the product.
piInstalled
[in] Specifies the returned current installed state. This parameter can be one of the following values.
Value | Meaning
INSTALLSTATE_BADCONFIG | The configuration data is corrupt.
INSTALLSTATE_INCOMPLETE | The installation is suspended or in progress.
INSTALLSTATE_SOURCEABSENT | The feature must run from source, and the source is unavailable.
INSTALLSTATE_MOREDATA | The return buffer is full.
INSTALLSTATE_INVALIDARG | An invalid parameter was passed to the function.
INSTALLSTATE_UNKNOWN | An unrecognized product or feature was specified.
INSTALLSTATE_BROKEN | The feature is broken.
INSTALLSTATE_ADVERTISED | advertised feature
INSTALLSTATE_ABSENT | The feature was uninstalled.
INSTALLSTATE_LOCAL | The feature was installed on the local drive.
INSTALLSTATE_SOURCE | The feature must run from source, CD-ROM, or network.
INSTALLSTATE_DEFAULT | The feature will be installed in the default location: local or source.

piAction
[out] Receives the action taken during the installation session. For return values, see piInstalled.

Return Values

ERROR_INVALID_HANDLE
An invalid or inactive handle was supplied.
ERROR_SUCCESS
The function succeeded.
ERROR_UNKNOWN_FEATURE
An unknown feature was requested.

Remarks

See Calling Database Functions From Programs.

Requirements

Windows NT/2000: Requires Windows NT 4.0 SP3 or later. Available as a redistributable.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in Msiquery.h.
Library: Use Msi.lib.
Unicode: Implemented as Unicode and ANSI versions on all platforms.

See Also

Installer Selection Functions


MsiGetFeatureValidStates

The MsiGetFeatureValidStates function returns a valid installation state.

UINT MsiGetFeatureValidStates(
  MSIHANDLE hInstall,     // installer handle
  LPCTSTR szFeature,      // feature name
  DWORD *pInstallState    // install state
);

Parameters

hInstall
[in] Handle to the installation.
szFeature
[in] Specifies the feature name.
pInstallState
[out] Receives the location to hold the valid installation states. This parameter is a combination of the following values. For each valid install state, a bit is set of value: (INSTALLSTATE).
Value | Meaning
INSTALLSTATE_ABSENT | The feature can be uninstalled.
INSTALLSTATE_ADVERTISED | The feature can be advertised.
INSTALLSTATE_LOCAL | The feature can be installed on the local drive.
INSTALLSTATE_SOURCE | The feature can be configured to run from source, CD-ROM, or network.
INSTALLSTATE_DEFAULT | The feature can be configured to use the default location: local or source.

Return Values

ERROR_FUNCTION_FAILED
The function failed.
ERROR_INVALID_HANDLE
An invalid or inactive handle was supplied.
ERROR_INVALID_HANDLE_STATE
An invalid handle state was supplied.
ERROR_INVALID_PARAMETER
An invalid parameter was passed to the function.
ERROR_SUCCESS
The function succeeded.
ERROR_UNKNOWN_FEATURE
An unknown feature was requested.

Remarks

See Calling Database Functions From Programs.

The MsiGetFeatureValidStates function determines state validity by querying all components that are linked to the specified feature without taking into account the current installed state of any component. If any of these components have a value of IRSOPTIONAL in the RunFromSource column, or if at least one component is marked IRSTLOCALONLY and at least one other component is marked IRSSOURCEONLY, then both INSTALLSTATE_LOCAL and INSTALLSTATE_SOURCE are valid states for the feature. If all components are set to IRSLOCALONLY, INSTALLSTATE_LOCAL is the only valid state. If all components are set to IRSSOURCEONLY, INSTALLSTATE_SOURCE is the only valid state.

Requirements

Windows NT/2000: Requires Windows NT 4.0 SP3 or later. Available as a redistributable.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in Msiquery.h.
Library: Use Msi.lib.
Unicode: Implemented as Unicode and ANSI versions on all platforms.

See Also

Installer Selection Functions


MsiGetLanguage

The MsiGetLanguage function returns the numeric language of the installation that is currently running.

LANGID MsiGetLanguage(
  MSIHANDLE hInstall   // installer handle
);

Parameters

hInstall
[in] Handle to the installation.

Return Values

If the function succeeds, the return value is the numeric LANGID for the install.

If the function fails, the return value can be the following value.

ERROR_INVALID_HANDLE
An invalid or inactive handle was supplied.

Remarks

The MsiGetLanguage function returns 0 if an installation is not running.

Requirements

Windows NT/2000: Requires Windows NT 4.0 SP3 or later. Available as a redistributable.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in Msiquery.h.
Library: Use Msi.lib.

See Also

Installer State Access Functions


MsiGetLastErrorRecord

The MsiGetLastErrorRecord function returns the error record that was last returned for the calling process. This function returns a handle that should be closed using MsiCloseHandle.

MSIHANDLE MsiGetLastErrorRecord();

Parameters

None.

Return Values

A handle to the error record. If the last function was successful, MsiGetLastErrorRecord returns a null MSIHANDLE.

Remarks

With the MsiGetLastErrorRecord function, field 1 of the record contains the installer error code. Other fields contain data specific to the particular error. The error record is released internally after this function is run.

If the record is passed to MsiProcessMessage, it is formatted by looking up the string in the current database. If there is no installation session but a product database is open, the format string may be obtained by a query on the Error table using the error code, followed by a call to MsiFormatRecord. If the error code is known, the parameters may be individually interpreted.

The following functions set the per-process error record or reset it to null if no error occurred (MsiGetLastErrorRecord also clears the error record after returning it).

  • MsiOpenDatabase
  • MsiDatabaseCommit
  • MsiDatabaseOpenView
  • MsiDatabaseImport
  • MsiDatabaseExport
  • MsiDatabaseMerge
  • MsiDatabaseGenerateTransform
  • MsiDatabaseApplyTransform
  • MsiViewExecute
  • MsiViewModify
  • MsiRecordSetStream
  • MsiGetSummaryInformation
  • MsiGetSourcePath
  • MsiGetTargetPath
  • MsiSetTargetPath
  • MsiGetComponentState
  • MsiSetComponentState
  • MsiGetFeatureState
  • MsiSetFeatureState
  • MsiGetFeatureCost
  • MsiGetFeatureValidStates
  • MsiSetInstallLevel

Note that it is recommended to use variables of type PMSIHANDLE because the installer closes PMSIHANDLE objects as they go out of scope, whereas you must close MSIHANDLE objects by calling MsiCloseHandle.

For example, if you use code like this:

MSIHANDLE hRec = MsiCreateRecord(3);

Change it to:

PMSIHANDLE hRec = MsiCreateRecord(3);

Requirements

Windows NT/2000: Requires Windows NT 4.0 SP3 or later. Available as a redistributable.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in Msiquery.h.
Library: Use Msi.lib.

See Also

Installer State Access Functions


MsiGetMode

The MsiGetMode function is used to determine whether the installer is currently running in a specified mode, as listed in the table. The function returns a Boolean value of TRUE or FALSE, indicating whether the specific property passed into the function is currently set (TRUE) or not set (FALSE).

BOOL MsiGetMode(
  MSIHANDLE hInstall,    // installer handle
  MSIRUNMODE iRunMode    // run mode
);

Parameters

hInstall
[in] Handle to the installation.
iRunMode
[in] Specifies the run mode. This parameter must have one of the following values.
Value | Meaning
MSIRUNMODE_ADMIN | The administrative mode is installing, or the product is installing.
MSIRUNMODE_ADVERTISE | The advertisements are installing or the product is installing or updating.
MSIRUNMODE_MAINTENANCE | An existing installation is being modified or there is a new installation.
MSIRUNMODE_ROLLBACKENABLED | Rollback is enabled.
MSIRUNMODE_LOGENABLED | The log file is active. It was enabled prior to the installation session.
MSIRUNMODE_OPERATIONS | Execute operations are spooling or they are in the determination phase.
MSIRUNMODE_REBOOTATEND | A reboot is necessary after a successful installation (settable).
MSIRUNMODE_REBOOTNOW | A reboot is necessary to continue the installation (settable).
MSIRUNMODE_CABINET | Files from cabinets and Media table files are installing.
MSIRUNMODE_SOURCESHORTNAMES | The source LongFileNames is suppressed through the PID_MSISOURCE summary property.
MSIRUNMODE_TARGETSHORTNAMES | The target LongFileNames is suppressed through the SHORTFILENAMES property.
MSIRUNMODE_RESERVED11 | Reserved for future use.
MSIRUNMODE_WINDOWS9X | The operating system is Windows® 95 or Windows 98.
MSIRUNMODE_ZAWENABLED | The operating system supports demand installation.
MSIRUNMODE_RESERVED14 | Reserved for future use.
MSIRUNMODE_RESERVED15 | Reserved for future use.
MSIRUNMODE_SCHEDULED | A custom action called from install script execution.
MSIRUNMODE_ROLLBACK | A custom action called from rollback execution script.
MSIRUNMODE_COMMIT | A custom action called from commit execution script.

Return Values

TRUE indicates the specific property passed into the function is currently set.

FALSE indicates the specific property passed into the function is currently not set.

Remarks

Note that not all the run mode values of iRunMode are available when calling MsiGetMode from a deferred custom action. For details, see Obtaining Context Information for Deferred Execution Custom Actions.

Requirements

Windows NT/2000: Requires Windows NT 4.0 SP3 or later. Available as a redistributable.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in Msiquery.h.
Library: Use Msi.lib.

See Also

Installer State Access Functions


MsiGetProperty

The MsiGetProperty function gets the value for an installer property.

UINT MsiGetProperty(
  MSIHANDLE hInstall,    // installer handle
  LPCTSTR szName,        // property identifier, case-sensitive
  LPTSTR szValueBuf,     // buffer for returned property value
  DWORD *pchValueBuf     // in/out buffer character count
);

Parameters

hInstall
[in] Handle to the installer.
szName
[in] Specifies the name of the property.
szValueBuf
[in] [out] The buffer that receives the value of the property.
pchValueBuf
[out] Specifies the in-buffer character count. The count does not include the terminating null.

Return Values

ERROR_INVALID_HANDLE
An invalid or inactive handle was supplied.
ERROR_INVALID_PARAMETER
An invalid parameter was passed to the function.
ERROR_MORE_DATA
A buffer was too small to hold the entire value.
ERROR_SUCCESS
The function succeeded.

Remarks

If the value for the property retrieved by the MsiGetProperty function is not defined, it is equivalent to a 0-length value. It is not an error.

If ERROR_MORE_DATA is returned, the parameter which is a pointer gives the size of the buffer required to hold the string. If ERROR_SUCCESS is returned, it gives the number of characters written to the string buffer. Therefore you can get the size of the buffer by passing in an empty string (for example "") for the parameter that specifies the buffer. Do not attempt to determine the size of the buffer by passing in a Null (value=0).

Requirements

Windows NT/2000: Requires Windows NT 4.0 SP3 or later. Available as a redistributable.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in Msiquery.h.
Library: Use Msi.lib.
Unicode: Implemented as Unicode and ANSI versions on all platforms.

See Also

Installer State Access Functions


MsiGetShortcutTarget

The MsiGetShortcutTarget function examines a shortcut and returns its product, feature name, and component if available.

UINT MsiGetShortcutTarget(
  LPCDSTR szShortcutTarget,    // path to shortcut link file
  LPDSTR szProductCode,        // fixed length buffer for product code
  LPDSTR szFeatureId,          // fixed length buffer for feature id
  LPDSTR szComponentCode,      // fixed length buffer for component code
);

Parameters

szShortcutTarget
[in] The full path to a shortcut.
szProductCode
[out] A GUID for the product code of the shortcut, if available. Can be NULL.

Size: cchProductCode + 1.

szFeatureId
[out] The feature name of the shortcut, if available. Can be NULL.

Size: cchMaxFeatureName + 1.

szComponentCode
[out] A GUID of the component code, if available. Can be NULL.

Size: cchComponentId + 1.

If return buffers are provided, they must be large enough for the return values and a terminating NULL, as defined in msi.h.

Return Values

ERROR_SUCCESS
The function succeeded.
ERROR_FUNCTION_FAILED
The function failed.

Remarks

If the function fails, and the shortcut exists, the regular contents of the shortcut may be accessed through the IShellLink interface.

Otherwise, the state of the target may be determined by using the Installer Selection Functions.

Requirements

Windows NT/2000: Requires Windows NT 4.0 SP3 or later. Available as a redistributable.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in Msiquery.h.
Library: Use Msi.lib.
Unicode: Implemented as Unicode and ANSI versions on all platforms.

See Also

Installer Selection Functions


MsiGetSourcePath

The MsiGetSourcePath function returns the full source path for a folder in the Directory table.

UINT MsiGetSourcePath(
  MSIHANDLE hInstall,   // installer handle
  LPCTSTR szFolder,     // folder identifier
  LPTSTR szPathBuf,     // buffer to return full path
  DWORD *pcchPathBuf    // in/out buffer character count
);

Parameters

hInstall
[in] Handle to the installation.
szFolder
[in] Specifies a record of the Directory table. If the directory is a root directory, this can be a value from the DefaultDir column. Otherwise it must be a value from the Directory column.
szPathBuf
[in] [out] A buffer to receive the full path.
pcchPathBuf
[out] Receives the in/out character count. The count does not include the terminating null.

Return Values

ERROR_DIRECTORY
The directory specified was not found in the Directory table.
ERROR_INVALID_HANDLE
An invalid or inactive handle was supplied.
ERROR_INVALID_PARAMETER
An invalid parameter was passed to the function.
ERROR_MORE_DATA
A buffer was too small to hold the entire value.
ERROR_SUCCESS
The function succeeded.

Remarks

If ERROR_MORE_DATA is returned, the parameter which is a pointer gives the size of the buffer required to hold the string. If ERROR_SUCCESS is returned, it gives the number of characters written to the string buffer. Therefore you can get the size of the buffer by passing in an empty string (for example "") for the parameter that specifies the buffer. Do not attempt to determine the size of the buffer by passing in a Null (value=0).

Requirements

Windows NT/2000: Requires Windows NT 4.0 SP3 or later. Available as a redistributable.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in Msiquery.h.
Library: Use Msi.lib.
Unicode: Implemented as Unicode and ANSI versions on all platforms.

See Also

Installer Location Functions


MsiGetSummaryInformation

The MsiGetSummaryInformation function obtains a handle to the _SummaryInformation stream for an installer database. This function returns a handle that should be closed using MsiCloseHandle.

UINT MsiGetSummaryInformation(
  MSIHANDLE hDatabase,       // database handle
  LPCTSTR szDatabasePath,    // path to database
  UINT uiUpdateCount,        // maximum number of updated values, 0
                             //  to open read-only
  MSIHANDLE *phSummaryInfo   // location to return summary information
                             //  handle
);

Parameters

hDatabase
[in] Handle to the database.
szDatabasePath
[in] Specifies the path to the database.
uiUpdateCount
[in] Specifies the maximum number of updated values.
phSummaryInfo
[out] Pointer to the location from which to receive the summary information handle.

Return Values

ERROR_INSTALL_PACKAGE_INVALID
The installation package is invalid.
ERROR_INVALID_HANDLE
An invalid or inactive handle was supplied.
ERROR_INVALID_PARAMETER
An invalid parameter was passed to the function.
ERROR_SUCCESS
The function succeeded.

Remarks

If the database specified by the MsiGetSummaryInformation function is not open, you must specify 0 for hDatabase and specify the path to the database in szDatabasePath. If the database is open, you must set szDatabasePath to 0.

If a value of uiCount greater than 0 is used to open an existing summary information stream, MsiSummaryInfoPersist must be called before closing the phSummaryInfo handle. Failing to do this will lose the existing stream information.

Note that it is recommended to use variables of type PMSIHANDLE because the installer closes PMSIHANDLE objects as they go out of scope, whereas you must close MSIHANDLE objects by calling MsiCloseHandle.

For example, if you use code like this:

MSIHANDLE hRec = MsiCreateRecord(3);

Change it to:

PMSIHANDLE hRec = MsiCreateRecord(3);

Requirements

Windows NT/2000: Requires Windows NT 4.0 SP3 or later. Available as a redistributable.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in Msiquery.h.
Library: Use Msi.lib.
Unicode: Implemented as Unicode and ANSI versions on all platforms.

See Also

Summary Information Property Functions


MsiGetTargetPath

The MsiGetTargetPath function returns the full target path for a folder in the Directory table.

UINT MsiGetTargetPath(
  MSIHANDLE hInstall,   // installer handle
  LPCTSTR szFolder,     // folder identifier
  LPTSTR szPathBuf,     // buffer to return full path
  DWORD *pcchPathBuf    // in/out buffer character count
);

Parameters

hInstall
[in] Handle to the installation.
szFolder
[in] Specifies the folder identifier. This is a primary key in the Directory table.
szPathBuf
[in] [out] A buffer to receive the full path.
pcchPathBuf
[out] Receives the in/out buffer character count. The count does not include the terminating null.

Return Values

ERROR_DIRECTORY
The directory specified was not found in the Directory table.
ERROR_INVALID_HANDLE
An invalid or inactive handle was supplied.
ERROR_INVALID_PARAMETER
An invalid parameter was supplied.
ERROR_MORE_DATA
A buffer was too small to hold the entire value.
ERROR_SUCCESS
The function succeeded.

Remarks

If ERROR_MORE_DATA is returned, the parameter which is a pointer gives the size of the buffer required to hold the string. If ERROR_SUCCESS is returned, it gives the number of characters written to the string buffer. Therefore you can get the size of the buffer by passing in an empty string (for example "") for the parameter that specifies the buffer. Do not attempt to determine the size of the buffer by passing in a Null (value=0).

For more information, see Calling Database Functions From Programs.

Requirements

Windows NT/2000: Requires Windows NT 4.0 SP3 or later. Available as a redistributable.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in Msiquery.h.
Library: Use Msi.lib.
Unicode: Implemented as Unicode and ANSI versions on all platforms.

See Also

Installer Location Functions


MsiOpenDatabase

The MsiOpenDatabase function opens a database file for data access. This function returns a handle that should be closed using MsiCloseHandle.

UINT MsiOpenDatabase(
  LPCTSTR szDatabasePath,  // path to database
  LPCTSTR szPersist,       // output database or predefined persist mode
  MSIHANDLE *phDatabase    // location to return database handle
);

Parameters

szDatabasePath
[in] Specifies the full path or relative path to the database file.
szPersist
[out] Receives the full path to the file or the persistence mode. You can use the szPersist parameter to direct the persistent output to a new file or to specify one of the following predefined persistence modes.
Value | Meaning
MSIDBOPEN_CREATEDIRECT | Create a new database, direct mode read/write.
MSIDBOPEN_CREATE | Create a new database, transact mode read/write.
MSIDBOPEN_DIRECT | Open a database direct read/write without transaction.
MSIDBOPEN_READONLY | Open a database read-only, no persistent changes.
MSIDBOPEN_TRANSACT | Open a database read/write in transaction mode.
MSIDBOPEN_PATCHFILE | Add this flag to indicate a patch file.

phDatabase
[out] Pointer to the location of the returned database handle.

Return Values

ERROR_CREATE_FAILED
The database could not be created.
ERROR_INVALID_PARAMETER
One of the parameters was invalid.
ERROR_OPEN_FAILED
The database could not be opened as requested.
ERROR_SUCCESS
The function succeeded.

Remarks

To make and save changes to a database first open the database in transaction (MSIDBOPEN_TRANSACT), create (MSIDBOPEN_CREATE or MSIDBOPEN_CREATEDIRECT), or direct (MSIDBOPEN_DIRECT) mode. After making the changes, always call MsiDatabaseCommit before closing the database handle. MsiDatabaseCommit flushes all buffers.

Always call MsiDatabaseCommit on a database that has been opened in direct mode (MSIDBOPEN_DIRECT or MSIDBOPEN_CREATEDIRECT) before closing the database's handle. Failure to do this may corrupt the database.

Because MsiOpenDatabase initiates database access it cannot be used with a running installation

Note that it is recommended to use variables of type PMSIHANDLE because the installer closes PMSIHANDLE objects as they go out of scope, whereas you must close MSIHANDLE objects by calling MsiCloseHandle.

For example, if you use code like this:

MSIHANDLE hRec = MsiCreateRecord(3);

Change it to:

PMSIHANDLE hRec = MsiCreateRecord(3);

Note When a database is opened as the output of another database, the summary information stream of the output database is actually a read-only mirror of the original database, and, thus, cannot be changed. Additionally, it is not persisted with the database. To create or modify the summary information for the output database, it must be closed and reopened.

Requirements

Windows NT/2000: Requires Windows NT 4.0 SP3 or later. Available as a redistributable.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in Msiquery.h.
Library: Use Msi.lib.
Unicode: Implemented as Unicode and ANSI versions on all platforms.

See Also

General Database Access Functions


MsiPreviewBillboard

The MsiPreviewBillboard function displays a billboard with the host control in the displayed dialog box.

UINT MsiPreviewBillboard(
  MSIHANDLE hPreview,     // preview handle (UI handle)
  LPCTSTR szControlName,  // name of control that accepts billboard
  LPCTSTR szBillboard     // name of billboard to display
);

Parameters

hPreview
[in] Handle to the preview.
szControlName
[in] Specifies the name of the host control.
szBillboard
[in] Specifies the name of the billboard to display.

Return Values

ERROR_FUNCTION_FAILED
The function failed.
ERROR_INVALID_HANDLE
An invalid or inactive handle was supplied.
ERROR_INVALID_PARAMETER
An invalid parameter was supplied.
ERROR_SUCCESS
The function succeeded.

Remarks

Supplying a NULL billboard name in the MsiPreviewBillboard function removes any billboard displayed.

Requirements

Windows NT/2000: Requires Windows NT 4.0 SP3 or later. Available as a redistributable.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in Msiquery.h.
Library: Use Msi.lib.
Unicode: Implemented as Unicode and ANSI versions on all platforms.

See Also

User Interface Functions


MsiPreviewDialog

The MsiPreviewDialog function displays a dialog box as modeless and inactive.

UINT MsiPreviewDialog(
  MSIHANDLE hPreview,     // preview handle (UI handle)
  LPCTSTR szDialogName    // name of dialog
);

Parameters

hPreview
[in] Handle to the preview.
szDialogName
[in] Specifies the name of the dialog box to preview.

Return Values

ERROR_FUNCTION_FAILED
The function failed.
ERROR_FUNCTION_NOT_CALLED
The function was not called.
ERROR_INSTALL_FAILURE
An installation failure occurred.
ERROR_INSTALL_SUSPEND
The installation was suspended.
ERROR_INSTALL_USEREXIT
The user exited the installation.
ERROR_INVALID_HANDLE
An invalid or inactive handle was supplied.
ERROR_INVALID_HANDLE_STATE
An invalid handle state was supplied.
ERROR_INVALID_PARAMETER
An invalid parameter was supplied.
ERROR_SUCCESS
The function succeeded.

Remarks

Supplying a NULL name in the MsiPreviewDialog function removes any current dialog box.

Requirements

Windows NT/2000: Requires Windows NT 4.0 SP3 or later. Available as a redistributable.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in Msiquery.h.
Library: Use Msi.lib.
Unicode: Implemented as Unicode and ANSI versions on all platforms.

See Also

User Interface Functions


MsiProcessMessage

The MsiProcessMessage function sends an error record to the installer for processing.

int MsiProcessMessage(
  MSIHANDLE hInstall,           // installer handle
  INSTALLMESSAGE eMessageType,  // type of message
  MSIHANDLE hRecord             // record handle
);

Parameters

hInstall
[in] Handle to the installation.
eMessageType
[in] Specifies the message type. This must be one of the following values.
Value | Meaning
INSTALLMESSAGE_FATALEXIT | Premature termination, possibly fatal out of memory.
INSTALLMESSAGE_ERROR Formatted error message,
[1] is message number in Error table.
INSTALLMESSAGE_WARNING Formatted warning message,
[1] is message number in Error table.
INSTALLMESSAGE_USER User request message,
[1] is message number in Error table.
INSTALLMESSAGE_INFO Informative message for log,
not to be displayed.
INSTALLMESSAGE_FILESINUSE | List of files in use that need to be replaced.
INSTALLMESSAGE_RESOLVESOURCE | Request to determine a valid source location.
INSTALLMESSAGE_OUTOFDISKSPACE | Insufficient disk space message.
INSTALLMESSAGE_ACTIONSTART Progress: start of action,
[1] action name,
[2] description,
[3] template for ACTIONDATA messages.
INSTALLMESSAGE_ACTIONDATA | Action data. Record fields correspond to the template of ACTIONSTART message.
INSTALLMESSAGE_PROGRESS | Progress bar information. See the description of record fields below.
INSTALLMESSAGE_COMMONDATA To enable the Cancel button set [1] to 2 and [2] to 1.

To disable the Cancel button set [1] to 2 and [2] to 0

hRecord
[in] Handle to a record containing message format and data.

Return Values

-1
An invalid parameter or handle was supplied.
0
No action was taken.
IDABORT
The process was stopped.
IDCANCEL
The process was canceled.
IDIGNORE
The process was ignored.
IDOK
The function succeeded.
IDNO
No.
IDRETRY
Retry.
IDYES
Yes.

Remarks

The MsiProcessMessage function performs any enabled logging operations and defers execution. You can selectively enable logging for various message types.

For INSTALLMESSAGE_FATALEXIT, INSTALLMESSAGE_ERROR, INSTALLMESSAGE_WARNING, and INSTALLMESSAGE_USER messages, if field 0 is not set field 1 must be set to the error code corresponding to the error message in the Error table. Then, the message is formatted using the template from the Error table before passing it to the user-interface handler for display.

Record Fields for Progress Bar Messages

The following describes the record fields when eMessageType is set to INSTALLMESSAGE_PROGRESS. Field 1 specifies the type of the progress message. The meaning of the other fields depend upon the value in this field. The possible values that can be set into Field 1 are as follows.

Field 1 value | Field 1 description
0 | Resets progress bar and sets the expected total number of ticks in the bar.
1 | Provides information related to progress messages to be sent by the current action.
2 | Increments the progress bar.
3 | Enables an action (such as CustomAction) to add ticks to the expected total number of progress of the progress bar.

The meaning of Field 2 depends upon the value in Field 1 as follows.

Field 1 value | Field 2 description
0 | Expected total number of ticks in the progress bar.
1 | Number of ticks the progress bar moves for each ActionData message. This field is ignored if Field 3 is 0.
2 | Number of ticks the progress bar has moved.
3 | Number of ticks to add to total expected progress.

The meaning of Field 3 depends upon the value in Field 1 as follows.

Field 1 value | Field 3 value | Field 3 description
0 | 0 | Forward progress bar (left to right)
 | 1 | Backward progress bar (right to left)
1 | 0 | The current action will send explicit ProgressReport messages.
 | 1 | Increment the progress bar by the number of ticks specified in Field 2 each time an ActionData message is sent.
2 | Unused |
3 | Unused |

The meaning of Field 4 depends upon the value in Field 1 as follows.

Field 1 value | Field 4 value | Field 4 description
0 | 0 | Execution is in progress. In this case, the UI could calculate and display the time remaining.
 | 1 | Creating the execution script. In this case, the UI could display a message to please wait while the installer finishes preparing the installation.
1 | Unused |
2 | Unused |
3 | Unused |

For more information and a code sample, see Adding Custom Actions to the ProgressBar.

Requirements

Windows NT/2000: Requires Windows NT 4.0 SP3 or later. Available as a redistributable.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in Msiquery.h.
Library: Use Msi.lib.

See Also

Installer Action Functions, Sending Messages to Windows Installer Using MsiProcessMessage


MsiRecordClearData

The MsiRecordClearData function sets all fields in a record to NULL.

unsigned int MsiRecordClearData(
  MSIHANDLE hRecord   // record handle
);

Parameters

hRecord
[in] Handle to the record.

Return Values

ERROR_INVALID_HANDLE
The handle is inactive or does not represent a record.
ERROR_SUCCESS
The function succeeded.

Requirements

Windows NT/2000: Requires Windows NT 4.0 SP3 or later. Available as a redistributable.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in Msiquery.h.
Library: Use Msi.lib.

See Also

Record Processing Functions


MsiRecordDataSize

The MsiRecordDataSize function returns the length of a record field. The count does not include the terminating null.

unsigned int MsiRecordDataSize(
  MSIHANDLE hRecord,    // record handle
  unsigned int iField   // record field
);

Parameters

hRecord
[in] Handle to the record.
iField
[in] Specifies a field of the record.

Return Values

The MsiRecordDataSize function returns 0 if the field is NULL, non-existent, or an internal object pointer. The function also returns 0 if the handle is not a valid record handle.

If the data is in integer format, the function returns sizeof(int).

If the data is in string format, the function returns the character count (not including the NULL terminator).

If the data is in stream format, the function returns the byte count.

Requirements

Windows NT/2000: Requires Windows NT 4.0 SP3 or later. Available as a redistributable.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in Msiquery.h.
Library: Use Msi.lib.

See Also

Record Processing Functions


MsiRecordGetFieldCount

The MsiRecordGetFieldCount function returns the number of fields in a record.

unsigned int MsiRecordGetFieldCount(
  MSIHANDLE hRecord    // record handle
);

Parameters

hRecord
[in] Handle to a record.

Return Values

If the function succeeds, the return value is the number of fields in the record.

If the function is given an invalid or inactive handle, it returns -1 or 0xFFFFFFFF.

Remarks

The count returned by the MsiRecordGetFieldCount parameter does not include field 0. Read access to fields beyond this count returns NULL values. Write access fails.

Requirements

Windows NT/2000: Requires Windows NT 4.0 SP3 or later. Available as a redistributable.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in Msiquery.h.
Library: Use Msi.lib.

See Also

Record Processing Functions


MsiRecordGetInteger

The MsiRecordGetInteger function returns the integer value from a record field.

int MsiRecordGetInteger(
  MSIHANDLE hRecord,    // record handle
  unsigned int iField   // field of record
);

Parameters

hRecord
[in] Handle to a record.
iField
[in] Specifies the field of the record from which to obtain the value.

Return Values

If the function succeeds, the return value is the integer value of the field.

Remarks

The MsiRecordGetInteger function returns MSI_NULL_INTEGER if the field is NULL or if the field is a string that cannot be converted to an integer.

Requirements

Windows NT/2000: Requires Windows NT 4.0 SP3 or later. Available as a redistributable.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in Msiquery.h.
Library: Use Msi.lib.

See Also

Record Processing Functions


MsiRecordGetString

The MsiRecordGetString function returns the string value of a record field.

UINT MsiRecordGetString(
  MSIHANDLE hRecord,     // record handle
  unsigned int iField,   // field requested
  LPTSTR szValueBuf,     // buffer to hold string
  DWORD *pcchValueBuf    // pointer to size of buffer
);

Parameters

hRecord
[in] Handle to the record.
iField
[in] Specifies the field requested.
szValueBuf
[in] [out] A buffer to receive the returned string.
pcchValueBuf
[out] Pointer to the size of the buffer. The count does not include the terminating null.

Return Values

ERROR_INVALID_HANDLE
An invalid or inactive handle was supplied.
ERROR_INVALID_PARAMETER
An invalid parameter was supplied.
ERROR_MORE_DATA
A buffer was too small to hold the entire value.
ERROR_SUCCESS
The function succeeded.

Remarks

If ERROR_MORE_DATA is returned, the parameter which is a pointer gives the size of the buffer required to hold the string. If ERROR_SUCCESS is returned, it gives the number of characters written to the string buffer. To get the size of the buffer, pass in szBuf as 1 and specify the size of the buffer with pcchValueBuf as 0. This ensures that no string value returned by the function will fit into the buffer. Do not attempt to determine the size of the buffer by passing in a Null (value=0).

Requirements

Windows NT/2000: Requires Windows NT 4.0 SP3 or later. Available as a redistributable.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in Msiquery.h.
Library: Use Msi.lib.
Unicode: Implemented as Unicode and ANSI versions on all platforms.

See Also

Record Processing Functions


MsiRecordIsNull

The MsiRecordIsNull function reports whether a record field is NULL.

BOOL MsiRecordIsNull(
  MSIHANDLE hRecord,    // record handle
  unsigned int iField   // field of record
);

Parameters

hRecord
[in] Handle to the record.
iField
[in] Specifies the field to check.

Return Values

ERROR_INVALID_HANDLE
An invalid or inactive handle was supplied.
FALSE
The function succeeded and the field is not null or the record handle is invalid.
TRUE
The function succeeded and the field is null or the field does not exist.

Remarks

The iField parameter is based on 1.

Requirements

Windows NT/2000: Requires Windows NT 4.0 SP3 or later. Available as a redistributable.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in Msiquery.h.
Library: Use Msi.lib.

See Also

Record Processing Functions


MsiRecordReadStream

The MsiRecordReadStream function reads bytes from a record stream field into a buffer.

UINT MsiRecordReadStream(
  MSIHANDLE hRecord,      // record handle
  UINT iField,            // field of record
  char *szDataBuf,        // buffer to receive bytes from stream
  DWORD *pcbDataBuf       // in/out buffer count
);

Parameters

hRecord
[in] Handle to the record.
iField
[in] Specifies the field of the record.
szDataBuf
[in] [out] A buffer to receive the stream field.
pcbDataBuf
[out] Specifies the in and out buffer count. The count does not include the terminating null.

Return Values

ERROR_INVALID_DATATYPE
The field is not a stream column.
ERROR_INVALID_HANDLE
An invalid or inactive handle was supplied.
ERROR_INVALID_PARAMETER
An invalid parameter was passed to the function.
ERROR_SUCCESS
The function succeeded.

Remarks

To read a stream, set pcbDataBuf to the number of bytes that are to be transferred from stream to buffer each time the function is called. On return, the MsiRecordReadStream resets pcbDataBuf to the number of bytes that were actually transferred. If the buffer is smaller than the stream, the stream is repositioned when the buffer becomes full such that the next data in the stream is transferred by the next call to the function. When no more bytes are available, MsiRecordReadStream returns ERROR_SUCCESS.

If you pass 0 for szDataBuf then pcbDataBuf is reset to the number of bytes in the stream remaining to be read.

The following code sample reads from a stream that is in field 1 of a record specified by hRecord and reads the entire stream 8 bytes at a time.

char szBuffer[8];
DWORD cbBuf = 8;
do
    {
    if (MsiRecordReadStream(hRecord, 1, szBuffer,
        &cbBuf) !=ERROR_SUCCESS)
        break; /* error */
    }
while (cbBuf == 8);

See also OLE Limitations on Streams.

Requirements

Windows NT/2000: Requires Windows NT 4.0 SP3 or later. Available as a redistributable.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in Msiquery.h.
Library: Use Msi.lib.

See Also

Record Processing Functions


MsiRecordSetInteger

The MsiRecordSetInteger function sets a record field to an integer field.

UINT MsiRecordSetInteger(
  MSIHANDLE hRecord,     // record handle
  unsigned int iField,   // field of record
  int iValue             // value to set
);

Parameters

hRecord
[in] Handle to the record.
iField
[in] Specifies the field of the record to set.
iValue
[in] Specifies the value to which to set the field.

Return Values

ERROR_INVALID_FIELD
An invalid field of the record was supplied.
ERROR_INVALID_HANDLE
An invalid or inactive handle was supplied.
ERROR_INVALID_PARAMETER
An invalid parameter was passed to the function.
ERROR_SUCCESS
The function succeeded.

Remarks

In the MsiRecordSetInteger function, attempting to store a value in a non-existent field causes an error. Note that the following code returns ERROR_INVALID_PARAMETER.

MSIHANDLE hRecord;
hRecord = MsiCreateRecord(0);
lReturn = MsiRecordSetInteger(hRecord, 1, 0);

To set a record integer field to NULL_INTEGER, set iValue to MSI_NULL_INTEGER.

Requirements

Windows NT/2000: Requires Windows NT 4.0 SP3 or later. Available as a redistributable.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in Msiquery.h.
Library: Use Msi.lib.

See Also

Record Processing Functions


MsiRecordSetStream

The MsiRecordSetStream function sets a record stream field from a file. Stream data cannot be inserted into temporary fields.

UINT MsiRecordSetStream(
  MSIHANDLE hRecord,      // record handle
  UNIT iField,            // field of record
  LPCTSTR szFilePath      // path to file containing stream
);

Parameters

hRecord
[in] Handle to the record.
iField
[in] Specifies the field of the record to set.
szFilePath
[in] Specifies the path to the file containing the stream.

Return Values

ERROR_BAD_PATHNAME
An invalid path was supplied.
ERROR_FUNCTION_FAILED
The function failed.
ERROR_INVALID_HANDLE
An invalid or inactive handle was supplied.
ERROR_INVALID_PARAMETER
An invalid parameter was passed to the function.
ERROR_SUCCESS
The function succeeded.

Remarks

The contents of the file specified in the MsiRecordSetStream function is read into a stream object. The stream persists if the record is inserted into the database and the database is committed.

To reset the stream to its beginning you must pass in a Null pointer for szFilePath. Do not pass a pointer to an empty string, "", to reset the stream.

See also OLE Limitations on Streams.

Requirements

Windows NT/2000: Requires Windows NT 4.0 SP3 or later. Available as a redistributable.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in Msiquery.h.
Library: Use Msi.lib.
Unicode: Implemented as Unicode and ANSI versions on all platforms.

See Also

Record Processing Functions


MsiRecordSetString

The MsiRecordSetString function copies a string into the designated field.

UINT MsiRecordSetString(
  MSIHANDLE hRecord,     // record handle
  unsigned int iField,   // field to set
  LPCTSTR szValue        // string value
);

Parameters

hRecord
[in] Handle to the record.
iField
[in] Specifies the field of the record to set.
szValue
[in] Specifies the string value of the field.

Return Values

ERROR_INVALID_HANDLE
An invalid or inactive handle was supplied.
ERROR_INVALID_PARAMETER
An invalid parameter was passed to the function.
ERROR_SUCCESS
The function succeeded.

Remarks

In the MsiRecordSetString function, a NULL string pointer and an empty string both set the field to NULL. Attempting to store a value in a non-existent field causes an error.

To set a record string field to NULL, set szValue to either a NULL string or an empty string.

Requirements

Windows NT/2000: Requires Windows NT 4.0 SP3 or later. Available as a redistributable.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in Msiquery.h.
Library: Use Msi.lib.
Unicode: Implemented as Unicode and ANSI versions on all platforms.

See Also

Record Processing Functions


MsiSequence

The MsiSequence function executes another action sequence, as described in the specified table.

UINT MsiSequence(
  MSIHANDLE hInstall,    // installer handle
  LPCTSTR szTable,       // table name
  INT iSequenceMode      // processing option
);

Parameters

hInstall
[in] Handle to the installation.
szTable
[in] Specifies the name of the table containing the action sequence.
iSequenceMode
[in] This parameter is currently unimplemented. It is reserved for future use and must be 0.

Return Values

ERROR_FUNCTION_FAILED
The function failed.
ERROR_FUNCTION_NOT_CALLED
The function was not called.
ERROR_INSTALL_FAILURE
An installation failure occurred.
ERROR_INSTALL_SUSPEND
The installation was suspended.
ERROR_INSTALL_USEREXIT
The user exited the installation.
ERROR_INVALID_HANDLE
An invalid or inactive handle was supplied.
ERROR_INVALID_HANDLE_STATE
An invalid handle state occurred.
ERROR_INVALID_PARAMETER
An invalid parameter was passed to the function.
ERROR_SUCCESS
The function succeeded.

Remarks

The MsiSequence function queries the specified table, ordering the actions by the numbers in the Sequence column. For each row retrieved, an action is executed, provided that any supplied condition expression does not evaluate to FALSE.

An action sequence containing any actions that update the system, such as the InstallFiles and WriteRegistryValues actions, cannot be run by calling MsiSequence. The exception to this rule is if MsiSequence is called from a custom action that is scheduled in the InstallExecuteSequence table between the InstallInitialize and InstallFinalize actions. Actions that do not update the system, such as AppSearch or CostInitialize, can be called.

Requirements

Windows NT/2000: Requires Windows NT 4.0 SP3 or later. Available as a redistributable.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in Msiquery.h.
Library: Use Msi.lib.
Unicode: Implemented as Unicode and ANSI versions on all platforms.

See Also

Installer Action Functions


MsiSetComponentState

The MsiSetComponentState function sets a component to the requested state.

UINT MsiSetComponentState(
  MSIHANDLE hInstall,     // installer handle
  LPCTSTR szComponent,    // name of component within product
  INSTALLSTATE iState     // install state
);

Parameters

hInstall
[in] Handle to the installation.
szComponent
[in] Specifies the name of the component.
iState
[in] Specifies the state to set. This parameter can be one of the following values.
Value | Meaning
INSTALLSTATE_ABSENT | The component was uninstalled.
INSTALLSTATE_LOCAL | The component was installed on the local drive.
INSTALLSTATE_SOURCE | The component will run from source, CD, or network.

Return Values

ERROR_FUNCTION_FAILED
The function failed.
ERROR_INSTALL_USEREXIT
The user exited the installation.
ERROR_INVALID_HANDLE
An invalid or inactive handle was supplied.
ERROR_SUCCESS
The function succeeded.
ERROR_UNKNOWN_COMPONENT
An unknown component was requested.

Remarks

The MsiSetComponentState function requests a change in the Action state of a record in the Component table.

Note that Windows Installer version 1.0 does not return ERROR_INSTALL_USEREXIT.

See Calling Database Functions From Programs.

Requirements

Windows NT/2000: Requires Windows NT 4.0 SP3 or later. Available as a redistributable.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in Msiquery.h.
Library: Use Msi.lib.
Unicode: Implemented as Unicode and ANSI versions on all platforms.

See Also

Installer Selection Functions


MsiSetFeatureAttributes

The MsiSetFeatureAttributes function can modify the default attributes of a feature at runtime. Note that the default attributes of features are authored in the Attributes column of the Feature table.

UINT MsiSetFeatureAttributes(
  MSIHANDLE hInstall,  // handle to the product that owns the feature
  LPCTSTR szFeature,   // specifies the feature name within the product
  DWORD dwAttributes   // attributes defied as set of bit flags
);

Parameters

hInstall
[in] Handle to the product that owns the feature. This handle can be obtained by calling MsiOpenPackage.
szFeature
[in] Specifies the feature name within the product.
dwAttributes
[in] Feature attributes specified at run time as a set of bit flags:
Constant | Value | Description
INSTALLFEATUREATTRIBUTE_FAVORLOCAL | 1 | Modifies default feature attributes to msidbFeatureAttributesFavorLocal at run time. See Attributes column of the Feature table for a description.
INSTALLFEATUREATTRIBUTE_FAVORSOURCE | 2 | Modifies default feature attributes to msidbFeatureAttributesFavorSource at run time. See Attributes column of the Feature table for a description.
INSTALLFEATUREATTRIBUTE_FOLLOWPARENT | 4 | Modifies default feature attributes to msidbFeatureAttributesFollowParent at run time. Note that this is not a valid attribute to be set for top-level features. See Attributes column of the Feature table for a description.
INSTALLFEATUREATTRIBUTE_FAVORADVERTISE | 8 | Modifies default feature attributes to msidbFeatureAttributesFavorAdvertise at run time. See Attributes column of the Feature table for a description.
INSTALLFEATUREATTRIBUTE_DISALLOWADVERTISE | 16 | Modifies default feature attributes to msidbFeatureAttributesDisallowAdvertise at run time. See Attributes column of the Feature table for a description.
INSTALLFEATUREATTRIBUTE_NOUNSUPPORTEDADVERTISE | 32 | Modifies default feature attributes to msidbFeatureAttributesNoUnsupportedAdvertise at run time. See Attributes column of the Feature table for a description.

Return Values

ERROR_SUCCESS
The function returned successfully.
ERROR_INVALID_HANDLE
The product handle is invalid.
ERROR_UNKNOWN_FEATURE
The feature is not known.
ERROR_FUNCTION_FAILED
The function was called at an invalid time during the install, before the CostInitialize action or after the CostFinalize action.

Remarks

MsiSetFeatureAttributes must be called after CostInitialize action and before CostFinalize action. The function returns ERROR_FUNCTION_FAILED if called at any other time.

The INSTALLFEATUREATTRIBUTE_FAVORLOCAL, INSTALLFEATUREATTRIBUTE_FAVORSOURCE, and INSTALLFEATUREATTRIBUTE_FOLLOWPARENT flags are mutually exclusive. Only one of these bits can be set for any feature. If more than one of these flags is set, the behavior of that feature is undefined.

See Calling Database Functions From Programs.

This function is not available with Windows Installer version 1.0.

Requirements

Windows NT/2000: Requires Windows NT 4.0 SP3 or later. Available as a redistributable.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in Msiquery.h.
Library: Use Msi.lib.
Unicode: Implemented as Unicode and ANSI versions on all platforms.


MsiSetFeatureState

The MsiSetFeatureState function sets a feature to a specified state.

UINT MsiSetFeatureState(
  MSIHANDLE hInstall,     // installer handle
  LPCTSTR szFeature,      // name of feature
  INSTALLSTATE iState     // install state
);

Parameters

hInstall
[in] Handle to the installation.
szFeature
[in] Specifies the name of the feature.
iState
[in] Specifies the state to set. This parameter can be one of the following values.
Value | Meaning
INSTALLSTATE_ABSENT | The feature is not installed.
INSTALLSTATE_LOCAL | The feature is installed on the local drive.
INSTALLSTATE_SOURCE | The feature is run from source, CD, or network.
INSTALLSTATE_ADVERTISED | The feature is advertised.

Return Values

ERROR_FUNCTION_FAILED
The function failed.
ERROR_INVALID_HANDLE
An invalid or inactive handle was supplied.
ERROR_INVALID_PARAMETER
One of the parameters was invalid.
ERROR_SUCCESS
The function succeeded.
ERROR_UNKNOWN_FEATURE
An unknown feature was requested.

Remarks

The MsiSetFeatureState function requests a change in the select state of a feature in the Feature table and its children. In turn, the Action state of all the components linked to the changed Feature records are also updated appropriately, based on the new feature Select state.

The MsiSetInstallLevel function must be called before calling MsiSetFeatureState.

When MsiSetFeatureState is called, the installer attempts to set the Action state of each component tied to the specified feature to the specified state. However, there are common situations when the request cannot be fully implemented. For example, suppose a feature is tied to two components, component A and component B, through the FeatureComponents table. Also suppose that component A is authored with a RunFromSource option of IRSLOCALONLY and component B is authored with a RunFromSource option of IRSSOURCEONLY. In this case, if MsiSetFeatureState is called with a requested state of either INSTALLSTATE_LOCAL or INSTALLSTATE_SOURCE, the request cannot be fully implemented for both components. However, both components are turned ON, with component A set to Local and component B set to Source.

If more than one feature is linked to a single component (a common scenario), the final Action state of that component is determined as follows.

  • If at least one feature requires the component to be installed locally, the feature is installed with a state of Local.
  • If at least one feature requires the component to be run from source , the feature is installed with a state of Source.
  • If at least one feature requires the removal of the component, the action state is Absent.

See Calling Database Functions From Programs.

Requirements

Windows NT/2000: Requires Windows NT 4.0 SP3 or later. Available as a redistributable.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in Msiquery.h.
Library: Use Msi.lib.
Unicode: Implemented as Unicode and ANSI versions on all platforms.

See Also

Installer Selection Functions


MsiSetInstallLevel

The MsiSetInstallLevel function sets the installation level for a full product installation.

UINT MsiSetInstallLevel(
  MSIHANDLE hInstall,   // installer handle
  int iInstallLevel     // install level
);

Parameters

hInstall
[in] Handle to the installation.
iInstallLevel
[in] Specifies the installation level.

Return Values

ERROR_FUNCTION_FAILED
The function failed.
ERROR_INVALID_HANDLE
An invalid or inactive handle was supplied.
ERROR_SUCCESS
The function succeeded.

Remarks

The MsiSetInstallLevel function sets the following.

  • The installation level for the current installation to a specified value.
  • The Select and Installed states for all features in the Feature table.
  • The Action state of each component in the Component table, based on the new level.

If 0 or a negative number is passed in the ilnstallLevel parameter, the current installation level does not change, but all features are still updated based on the current installation level.

See Calling Database Functions From Programs.

Requirements

Windows NT/2000: Requires Windows NT 4.0 SP3 or later. Available as a redistributable.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in Msiquery.h.
Library: Use Msi.lib.

See Also

Installer Selection Functions


MsiSetMode

The MsiSetMode function sets an internal engine Boolean state.

UINT MsiSetMode(
  MSIHANDLE hInstall,     // installer handle
  unsigned int iRunMode,  // run mode
  BOOL fState             // state to set
);

Parameters

hInstall
[in] Handle to the installer.
iRunMode
[in] Specifies the run mode. This parameter must be one of the following values. While there are many values for this parameter, as described in MsiGetMode, only one of the following values can be set.
Value | Meaning
MSIRUNMODE_REBOOTATEND | A reboot is necessary after a successful installation.
MSIRUNMODE_REBOOTNOW | A reboot is necessary to continue installation.

fState
[in] Specifies the state to set to TRUE or FALSE.

Return Values

ERROR_ACCESS_DENIED
Access was denied.
ERROR_INVALID_HANDLE
An invalid or inactive handle was supplied.
ERROR_SUCCESS
The function succeeded.

Requirements

Windows NT/2000: Requires Windows NT 4.0 SP3 or later. Available as a redistributable.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in Msiquery.h.
Library: Use Msi.lib.

See Also

Installer State Access Functions


MsiSetProperty

The MsiSetProperty function sets the value for an installation property.

UINT MsiSetProperty(
  MSIHANDLE hInstall,   // installer handle
  LPCTSTR szName,       // property identifier, case-sensitive
  LPCTSTR szValue       // property value, NULL to undefine property
);

Parameters

hInstall
[in] Handle to the installer.
szName
[in] Specifies the name of the property.
szValue
[in] Specifies the value of the property.

Return Values

ERROR_FUNCTION_FAILED
The function failed.
ERROR_INVALID_HANDLE
An invalid or inactive handle was supplied.
ERROR_INVALID_PARAMETER
An invalid parameter was passed to the function.
ERROR_SUCCESS
The function succeeded.

Remarks

If the property is not defined, it is created by the MsiSetProperty function. If the value is NULL or an empty string, the property is removed.

Requirements

Windows NT/2000: Requires Windows NT 4.0 SP3 or later. Available as a redistributable.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in Msiquery.h.
Library: Use Msi.lib.
Unicode: Implemented as Unicode and ANSI versions on all platforms.

See Also

Installer State Access Functions


MsiSetTargetPath

The MsiSetTargetPath function sets the full target path for a folder in the Directory table.

UINT MsiSetTargetPath(
  MSIHANDLE hInstall,   // installer handle
  LPCTSTR szFolder,     // folder identifier
  LPCTSTR szFolderPath  // full path for folder, ending in
                        //  directory separator
);

Parameters

hInstall
[in] Handle to the installation.
szFolder
[in] Specifies the folder identifier. This is a primary key in the Directory table.
szFolderPath
[in] Specifies the full path for the folder, ending in a directory separator.

Return Values

ERROR_DIRECTORY
The directory specified was not found in the Directory table.
ERROR_INVALID_HANDLE
An invalid or inactive handle was supplied.
ERROR_INVALID_PARAMETER
An invalid parameter was passed to the function.
ERROR_SUCCESS
The function succeeded.

Remarks

The MsiSetTargetPath function changes the path specification for the target directory named in the in-memory Directory table. Also, the path specifications of all other path objects in the table that are either subordinate or equivalent to the changed path are updated to reflect the change. The properties for each affected path are also updated.

MsiSetTargetPath fails if the selected directory is read only.

If an error occurs in this function, all updated paths and properties revert to their previous values. Therefore, it is safe to treat errors returned by this function as non-fatal.

Do not attempt to configure the target path if the components using those paths are already installed for the current user or for a different user. Check the ProductState property before calling MsiSetTargetPath to determine if the product containing this component is installed.

See Calling Database Functions From Programs.

Requirements

Windows NT/2000: Requires Windows NT 4.0 SP3 or later. Available as a redistributable.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in Msiquery.h.
Library: Use Msi.lib.
Unicode: Implemented as Unicode and ANSI versions on all platforms.

See Also

Installer Location Functions


MsiSummaryInfoGetProperty

The MsiSummaryInfoGetProperty function gets a single property from the summary information.

UINT MsiSummaryInfoGetProperty(
  MSIHANDLE hSummaryInfo,   // summary info handle
  UINT uiProperty,          // property
  UINT *puiDataType,        // property type
  INT *piValue,             // value
  FILETIME *pftValue,       // file time
  LPTSTR szValueBuf,       // value buffer
  DWORD *pcchValueBuf       // buffer size
);

Parameters

hSummaryInfo
[in] Handle to summary information.
uiProperty
[in] Specifies the property ID.
puiDataType
[in] Specifies the returned property type. This type can be VT_I2, VT_I4, VT_LPSTR, VT_FILETIME, or VT_EMPTY. For more information on these types, see Summary Information Stream Property Set.
piValue
[out] Receives the returned integer property data.
pftValue
[out] Pointer to a file value.
szValueBuf
[in] [out] A buffer to receive string property data.
pcchValueBuf
[out] Receives the size of the string buffer. The count does not include the terminating null.

Return Values

ERROR_INVALID_HANDLE
An invalid or inactive handle was supplied.
ERROR_INVALID_PARAMETER
An invalid parameter was passed to the function.
ERROR_MORE_DATA
A buffer was too small to hold the entire value.
ERROR_SUCCESS
The function succeeded.
ERROR_UNKNOWN_PROPERTY
The property is unknown.

Remarks

If ERROR_MORE_DATA is returned, the parameter which is a pointer gives the size of the buffer required to hold the string. If ERROR_SUCCESS is returned, it gives the number of characters written to the string buffer. Therefore you can get the size of the buffer by passing in an empty string (for example "") for the parameter that specifies the buffer. Do not attempt to determine the size of the buffer by passing in a Null (value=0).

Requirements

Windows NT/2000: Requires Windows NT 4.0 SP3 or later. Available as a redistributable.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in Msiquery.h.
Library: Use Msi.lib.
Unicode: Implemented as Unicode and ANSI versions on all platforms.

See Also

Summary Information Property Functions


MsiSummaryInfoGetPropertyCount

The MsiSummaryInfoGetPropertyCount function returns the number of existing properties in the summary information stream.

UINT MsiSummaryInfoGetPropertyCount(
  MSIHANDLE hSummaryInfo, // summary information handle
  UINT *puiPropertyCount  // location to return total property count
);

Parameters

hSummaryInfo
[in] Handle to summary information.
puiPropertyCount
[out] Location to receive the total property count.

Return Values

ERROR_INVALID_HANDLE
An invalid or inactive handle was supplied.
ERROR_SUCCESS
The function succeeded.

Requirements

Windows NT/2000: Requires Windows NT 4.0 SP3 or later. Available as a redistributable.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in Msiquery.h.
Library: Use Msi.lib.

See Also

Summary Information Property Functions


MsiSummaryInfoPersist

The MsiSummaryInfoPersist function writes changed summary information back to the summary information stream.

UINT MsiSummaryInfoPersist(
  MSIHANDLE hSummaryInfo    // summary info handle
);

Parameters

hSummaryInfo
[in] Handle to summary information.

Return Values

ERROR_FUNCTION_FAILED
The function failed.
ERROR_INVALID_HANDLE
An invalid or inactive handle was supplied.
ERROR_SUCCESS
The function succeeded.

Requirements

Windows NT/2000: Requires Windows NT 4.0 SP3 or later. Available as a redistributable.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in Msiquery.h.
Library: Use Msi.lib.

See Also

Summary Information Property Functions


MsiSummaryInfoSetProperty

The MsiSummaryInfoSetProperty function sets a single summary information property.

UINT MsiSummaryInfoSetProperty(
  MSIHANDLE hSummaryInfo, // summary information handle
  UINT uiProperty,        // property ID, one of allowed values
                          //  for summary information
  UINT uiDataType,        // VT_I4, VT_LPTSTR, VT_FILETIME,
                          //  or VT_EMPTY
  INT iValue,             // integer value, used only if integer
                          //  property
  FILETIME *pftValue,     // pointer to file-time value, used only
                          //  if date/time property
  LPTSTR szValue          // text value, used only if string property
);

Parameters

hSummaryInfo
[in] Handle to summary information.
uiProperty
[in] Specifies the property to set.
uiDataType
[in] Specifies the type of property to set.
iValue
[in] Specifies the integer value.
pftValue
[in] Specifies the file-time value.
szValue
[in] Specifies the text value.

Return Values

ERROR_DATATYPE_MISMATCH
The data types were mismatched.
ERROR_FUNCTION_FAILED
The function failed.
ERROR_INVALID_HANDLE
An invalid or inactive handle was supplied.
ERROR_INVALID_PARAMETER
An invalid parameter was passed to the function.
ERROR_SUCCESS
The function succeeded.
ERROR_UNKNOWN_PROPERTY
The summary information property is unknown.
ERROR_UNSUPPORTED_TYPE
The type is unsupported.

Requirements

Windows NT/2000: Requires Windows NT 4.0 SP3 or later. Available as a redistributable.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in Msiquery.h.
Library: Use Msi.lib.
Unicode: Implemented as Unicode and ANSI versions on all platforms.

See Also

Summary Information Property Functions


MsiVerifyDiskSpace

The MsiVerifyDiskSpace function checks to see if sufficient disk space is present for the current installation.

UINT MsiVerifyDiskSpace(
  MSIHANDLE hInstall    // installer handle
);

Parameters

hInstall
[in] Handle to the installation.

Return Values

ERROR_DISK_FULL
The disk is full.
ERROR_INVALID_HANDLE
An invalid or inactive handle was supplied.
ERROR_INVALID_HANDLE_STATE
The handle is in an invalid state.
ERROR_SUCCESS
The function succeeded.

Remarks

See Calling Database Functions From Programs.

Requirements

Windows NT/2000: Requires Windows NT 4.0 SP3 or later. Available as a redistributable.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in Msiquery.h.
Library: Use Msi.lib.

See Also

Installer Selection Functions


MsiViewClose

The MsiViewClose function releases the result set for an executed view.

UINT MsiViewClose(
  MSIHANDLE hView    // view handle
);

Parameters

hView
[in] Handle to a view that is set to release.

Return Values

ERROR_FUNCTION_FAILED
The function failed.
ERROR_INVALID_HANDLE
An invalid or inactive handle was supplied.
ERROR_INVALID_HANDLE_STATE
The handle is in an invalid state.
ERROR_SUCCESS
The function succeeded.

Remarks

The MsiViewClose function must be called before the MsiViewExecute function is called again on the view, unless all rows of the result set have been obtained with the MsiViewFetch function.

Requirements

Windows NT/2000: Requires Windows NT 4.0 SP3 or later. Available as a redistributable.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in Msiquery.h.
Library: Use Msi.lib.

See Also

General Database Access Functions


MsiViewExecute

The MsiViewExecute function executes a SQL view query and supplies any required parameters. The query uses the question mark token to represent parameters as described in SQL Syntax. The values of these parameters are passed in as the corresponding fields of a parameter record.

UINT MsiViewExecute(
  MSIHANDLE hView,    // view handle
  MSIHANDLE hRecord   // parameter record
);

Parameters

hView
[in] Handle to the view upon which to execute the query.
hRecord
[in] Handle to a record that supplies the parameters. This parameter contains values to replace the parameter tokens in the SQL query. It is optional, so hRecord can be zero. For a reference on syntax, see SQL Syntax.

Return Values

ERROR_FUNCTION_FAILED
A view could not be executed.
ERROR_INVALID_HANDLE
An invalid or inactive handle was supplied.
ERROR_SUCCESS
The function succeeded.

Remarks

The MsiViewExecute function must be called before any calls to MsiViewFetch.

If the SQL query specifies values with parameter markers (?), a record must be supplied containing all of the replacement values in the exact order and of compatible data types. When used with INSERT and UPDATE queries all the parameterized values must precede all non-parameterized values.

For example, these queries are valid.

UPDATE {table-list} SET {column}= ? , {column}= {constant}

INSERT INTO {table} ({column-list}) VALUES (?, {constant-list})

However these queries are invalid.

UPDATE {table-list} SET {column}= {constant}, {column}=?

INSERT INTO {table} ({column-list}) VALUES ({constant-list}, ? )

Requirements

Windows NT/2000: Requires Windows NT 4.0 SP3 or later. Available as a redistributable.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in Msiquery.h.
Library: Use Msi.lib.

See Also

General Database Access Functions


MsiViewFetch

The MsiViewFetch function fetches the next sequential record from the view. This function returns a handle that should be closed using MsiCloseHandle.

UINT MsiViewFetch(
  MSIHANDLE hView,      // view handle
  MSIHANDLE *phRecord   // handle for fetched record
);

Parameters

hView
[in] Handle to the view to fetch from.
phRecord
[in] Pointer to the handle for the fetched record.

Return Values

ERROR_FUNCTION_FAILED
An error occurred during fetching.
ERROR_INVALID_HANDLE
An invalid or inactive handle was supplied.
ERROR_INVALID_HANDLE_STATE
The handle was in an invalid state.
ERROR_NO_MORE_ITEMS
No records remain, and a NULL handle is returned.
ERROR_SUCCESS
The function succeeded, and a handle to the record is returned.

Remarks

If the MsiViewFetch function returns ERROR_FUNCTION_FAILED, it is possible that the MsiViewExecute function was not called first. If more rows are available in the result set, MsiViewFetch returns phRecord as a handle to a record containing the requested column data, or phRecord is 0. For maximum performance, the same record should be used for all retrievals, or the record should be released by going out of scope.

Note that it is recommended to use variables of type PMSIHANDLE because the installer closes PMSIHANDLE objects as they go out of scope, whereas you must close MSIHANDLE objects by calling MsiCloseHandle.

For example, if you use code like this:

MSIHANDLE hRec = MsiCreateRecord(3);

Change it to:

PMSIHANDLE hRec = MsiCreateRecord(3);

Requirements

Windows NT/2000: Requires Windows NT 4.0 SP3 or later. Available as a redistributable.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in Msiquery.h.
Library: Use Msi.lib.

See Also

General Database Access Functions


MsiViewGetColumnInfo

The MsiViewGetColumnInfo function returns a record containing column names or definitions. This function returns a handle that should be closed using MsiCloseHandle.

UINT MsiViewGetColumnInfo(
  MSIHANDLE hView,         // view handle
  MSICOLINFO eColumnInfo,  // type of information to return, names
                           //  or definitions
  MSIHANDLE *phRecord      // handle for returned record
);

Parameters

hView
[in] Handle to the view from which to obtain column information.
eColumnInfo
[in] Specifies a flag indicating what type of information is needed. This parameter must be one of the following values.
Value | Meaning
MSICOLINFO_NAMES | Column names are returned.
MSICOLINFO_TYPES | Definitions are returned.

phRecord
[out] Pointer to a handle to receive the column information data record.

Return Values

ERROR_INVALID_HANDLE
An invalid or inactive handle was supplied.
ERROR_INVALID_HANDLE_STATE
The view is not in an active state.
ERROR_INVALID_PARAMETER
An invalid MSICOLINFO column information enumeration value was passed to the function.
ERROR_SUCCESS
The function succeeded, and a handle to a record was returned.

Remarks

The column description returned by MsiViewGetColumnInfo is in the format described in the section: Column Definition Format. Each column is described by a string in the corresponding record field. The definition string consists of a single letter representing the data type followed by the width of the column (in characters when applicable, bytes otherwise). A width of zero designates an unbounded width (for example, long text fields and streams). An uppercase letter indicates that NULL values are allowed in the column.

Note that it is recommended to use variables of type PMSIHANDLE because the installer closes PMSIHANDLE objects as they go out of scope, whereas you must close MSIHANDLE objects by calling MsiCloseHandle.

For example, if you use code like this:

MSIHANDLE hRec = MsiCreateRecord(3);

Change it to:

PMSIHANDLE hRec = MsiCreateRecord(3);

Requirements

Windows NT/2000: Requires Windows NT 4.0 SP3 or later. Available as a redistributable.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in Msiquery.h.
Library: Use Msi.lib.


MsiViewGetError

The MsiViewGetError function returns the error that occurred in the MsiViewModify function.

MSIDBERROR MsiViewGetError(
  MSIHANDLE hView,            // view handle
  LPTSTR szColumnNameBuffer,  // buffer to hold column name string
  DWORD *pcchBuf              // size of buffer
);

Parameters

hView
[in] Handle to the view.
szColumnNameBuffer
[in] Specifies the buffer to hold the column name string. This parameter is NULL if there are no errors or if the size of the buffer is too small.
pcchBuf
[in] [out] Specifies the size of the buffer. This parameter returns the size required for the buffer if an error occurs. The count does not include the terminating null.

Return Values

This function returns one of the following values.

Error code | Meaning
MSIDBERROR_INVALIDARG | An argument was invalid.
MSIDBERROR_MOREDATA | The buffer was too small to receive data.
MSIDBERROR_FUNCTIONERROR | The function failed.
MSIDBERROR_NOERROR | The function completed successfully with no errors.
MSIDBERROR_DUPLICATEKEY | The new record duplicates primary keys of the existing record in a table.
MSIDBERROR_REQUIRED | There are no NULL values allowed, or the column is about to be deleted but is referenced by another row.
MSIDBERROR_BADLINK | The corresponding record in a foreign table was not found.
MSIDBERROR_OVERFLOW | The data is greater than the maximum value allowed.
MSIDBERROR_UNDERFLOW | The data is less than the minimum value allowed.
MSIDBERROR_NOTINSET | The data is not a member of the values permitted in the set.
MSIDBERROR_BADVERSION | An invalid version string was supplied.
MSIDBERROR_BADCASE | The case was invalid. The case must be all uppercase or all lowercase.
MSIDBERROR_BADGUID | An invalid GUID was supplied.
MSIDBERROR_BADWILDCARD | An invalid wildcard file name was supplied, or the use of wildcards was invalid.
MSIDBERROR_BADIDENTIFIER | An invalid identifier was supplied.
MSIDBERROR_BADLANGUAGE | Invalid language IDs were supplied.
MSIDBERROR_BADFILENAME | An invalid file name was supplied.
MSIDBERROR_BADPATH | An invalid path was supplied.
MSIDBERROR_BADCONDITION | An invalid conditional statement was supplied.
MSIDBERROR_BADFORMATTED | An invalid format string was supplied.
MSIDBERROR_BADTEMPLATE | An invalid template string was supplied.
MSIDBERROR_BADDEFAULTDIR | An invalid string was supplied in the DefaultDir column of the Directory table.
MSIDBERROR_BADREGPATH | An invalid registry path string was supplied.
MSIDBERROR_BADCUSTOMSOURCE | An invalid string was supplied in the CustomSource column of the CustomAction table.
MSIDBERROR_BADPROPERTY | An invalid property string was supplied.
MSIDBERROR_MISSINGDATA | The _Validation table is missing a reference to a column.
MSIDBERROR_BADCATEGORY | The category column of the _Validation table for the column is invalid.
MSIDBERROR_BADCABINET | An invalid cabinet name was supplied.
MSIDBERROR_BADKEYTABLE | The table in the Keytable column of the _Validation table was not found or loaded.
MSIDBERROR_BADMAXMINVALUES | The value in the MaxValue column of the _Validation table is less than the value in the MinValue column.
MSIDBERROR_BADSHORTCUT | An invalid shortcut target name was supplied.
MSIDBERROR_STRINGOVERFLOW | The string is too long for the length specified by the column definition.
MSIDBERROR_BADLOCALIZEATTRIB | An invalid localization attribute was supplied. (Primary keys cannot be localized.)

Remarks

You should only call the MsiViewGetError function when MsiViewModify returns ERROR_INVALID_DATA, indicating that the data is invalid. Errors are only recorded for MSIMODIFY_VALIDATE, MSIMODIFY_VALIDATE_NEW, and MSIMODIFY_VALIDATEFIELD.

If ERROR_MORE_DATA is returned, the parameter which is a pointer gives the size of the buffer required to hold the string. If ERROR_SUCCESS is returned, it gives the number of characters written to the string buffer. Therefore you can get the size of the buffer by passing in an empty string (for example "") for the parameter that specifies the buffer. Do not attempt to determine the size of the buffer by passing in a Null (value=0).

Requirements

Windows NT/2000: Requires Windows NT 4.0 SP3 or later. Available as a redistributable.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in Msiquery.h.
Library: Use Msi.lib.
Unicode: Implemented as Unicode and ANSI versions on all platforms.

See Also

General Database Access Functions


MsiViewModify

The MsiViewModify function updates a fetched record.

UINT MsiViewModify(
  MSIHANDLE hView,        // view handle
  MSIMODIFY eModifyMode,  // modify mode
  MSIHANDLE hRecord       // record handle
);

Parameters

hView
[in] Handle to a view.
eModifyMode
[in] Specifies the modify mode. This parameter can be one of the following values.
Value | Value | Meaning
MSIMODIFY_SEEK | -1 | Refreshes the information in the supplied record without changing the position in the result set and without affecting subsequent fetch operations. The record may then be used for subsequent Update, Delete, and Refresh. All primary key columns of the table must be in the query and the record must have at least as many fields as the query. Seek cannot be used with multi-table queries. This mode cannot be used with a view containing joins. See also the remarks.
MSIMODIFY_REFRESH | 0 | Refreshes the information in the record. Must first call MsiViewFetch with the same record. Fails for a deleted row. Works with read-write and read-only records.
MSIMODIFY_INSERT | 1 | Inserts a record. Fails if a row with the same primary keys exists. Fails with a read-only database. This mode cannot be used with a view containing joins.
MSIMODIFY_UPDATE | 2 | Updates an existing record. Non-primary keys only. Must first call MsiViewFetch. Fails with a deleted record. Works only with read-write records.
MSIMODIFY_ASSIGN | 3 | Writes current data in the cursor to a table row. Updates record if the primary keys match an existing row and inserts if they do not match. Fails with a read-only database. This mode cannot be used with a view containing joins.
MSIMODIFY_REPLACE | 4 | Updates or deletes and inserts a record into a table. Must first call MsiViewFetch with the same record. Updates record if the primary keys are unchanged. Deletes old row and inserts new if primary keys have changed. Fails with a read-only database. This mode cannot be used with a view containing joins.
MSIMODIFY_MERGE | 5 | Inserts or validates a record in a table. Inserts if primary keys do not match any row and validates if there is a match. Fails if the record does not match the data in the table. Fails if there is a record with a duplicate key that is not identical. Works only with read-write records. This mode cannot be used with a view containing joins.
MSIMODIFY_DELETE | 6 | Remove a row from the table. You must first call the MsiViewFetch function with the same record. Fails if the row has been deleted. Works only with read-write records. This mode cannot be used with a view containing joins.
MSIMODIFY_INSERT_TEMPORARY | 7 | Inserts a temporary record. The information is not persistent. Fails if a row with the same primary key exists. Works only with read-write records. This mode cannot be used with a view containing joins.
MSIMODIFY_VALIDATE | 8 | Validates a record. Does not validate across joins. You must first call the MsiViewFetch function with the same record. Obtain validation errors with MsiViewGetError. Works with read-write and read-only records. This mode cannot be used with a view containing joins.
MSIMODIFY_VALIDATE_NEW | 9 | Validate a new record. Does not validate across joins. Checks for duplicate keys. Obtain validation errors by calling MsiViewGetError. Works with read-write and read-only records. This mode cannot be used with a view containing joins.
MSIMODIFY_VALIDATE_FIELD | 10 | Validates fields of a fetched or new record. Can validate one or more fields of an incomplete record. Obtain validation errors by calling MsiViewGetError. Works with read-write and read-only records. This mode cannot be used with a view containing joins.
MSIMODIFY_VALIDATE_DELETE | 11 | Validates a record that will be deleted later. You must first call MsiViewFetch. Fails if another row refers to the primary keys of this row. Validation does not check for the existence of the primary keys of this row in properties or strings. Does not check if a column is a foreign key to multiple tables. Obtain validation errors by calling MsiViewGetError. Works with read-write and read-only records. This mode cannot be used with a view containing joins.

hRecord
[in] Handle to the record to modify.

Return Values

ERROR_ACCESS_DENIED
Access was not permitted.
ERROR_FUNCTION_FAILED
The function failed.
ERROR_INVALID_DATA
A validation was requested and the data did not pass. For more information, call MsiViewGetError.
ERROR_INVALID_HANDLE
An invalid or inactive handle was supplied.
ERROR_INVALID_HANDLE_STATE
The handle is in an invalid state.
ERROR_INVALID_PARAMETER
An invalid parameter was passed to the function.
ERROR_SUCCESS
The function succeeded.

Remarks

The MSIMODIFY_VALIDATE, MSIMODIFY_VALIDATE_NEW, MSIMODIFY_VALIDATE_FIELD, and MSIMODIFY_VALIDATE_DELETE values of the MsiViewModify function do not perform actual updates; they ensure that the data in the record is valid. Use of these validation enumerations requires that the database contains the _Validation table.

You can call MSIMODIFY_UPDATE or MSIMODIFY_DELETE with a record immediately after using MSIMODIFY_INSERT, MSIMODIFY_INSERT_TEMPORARY, or MSIMODIFY_SEEK provided you have NOT modified the 0th field of the inserted or sought record.

To execute any SQL statement, a view must be created. However, a view that does not create a result set, such as CREATE TABLE, or INSERT INTO, cannot be used with MsiViewModify to update tables though the view.

You cannot fetch a record containing binary data from one database and then use that record to insert the data into another database. To move binary data from one database to another, you should export the data to a file and then import it into the new database using a query and the MsiRecordSetStream. This ensures that each database has its own copy of the binary data.

Note that custom actions can only add, modify, or remove temporary rows, columns, or tables from a database. Custom actions cannot modify persistent data in a database, such as data that is a part of the database stored on disk. For more information, see How do I access the current installer session from inside a custom action?.

Requirements

Windows NT/2000: Requires Windows NT 4.0 SP3 or later. Available as a redistributable.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in Msiquery.h.
Library: Use Msi.lib.

See Also

General Database Access Functions


Database Tables

Following is a list of the Microsoft® Windows® Installer database tables.

Table name | Brief description of table
ActionText | Text in a progress dialog box or action log.
AdminExecuteSequence | Lists ADMIN actions in sequence.
AdminUISequence | Lists UI ADMIN actions in sequence.
AdvtExecuteSequence | Lists ADVERTISE actions in sequence.
AdvtUISequence | The installer does not use this table. The AdvtUISequence table should not exist in the installation database or it should be left empty.
AppSearch | Properties used to search by file signature.
MsiAssembly | Specifies Windows Installer settings for .NET Framework assemblies and Win32® assemblies
MsiAssemblyName | Specifies the schema for the elements of a strong assembly cache name for a .NET Framework or Win32 assembly.
BBControl | Lists controls displayed on each billboard.
Billboard | Lists billboards displayed in full UI.
Binary | Holds binary data for bitmaps and icons.
BindImage | Executables bound to the DLLs.
CCPSearch | File signatures for Compliance Checking Program.
CheckBox | Lists the values for the check boxes.
Class | COM server information for product advertisement.
ComboBox | Lists the values for each combo box.
CompLocator | Find file or directory by installer configuration data.
Complus | Contains information needed to install COM+ applications.
Component | Lists installation components.
Condition | Modifies feature selection states conditionally.
Control | Lists the controls on each dialog box.
ControlCondition | Actions applied to controls based on a property.
ControlEvent | Specifies the actions of controls in dialog boxes.
CreateFolder | Folders that must be created for a component.
CustomAction | Integrates custom actions into the installation.
Dialog | Lists dialog boxes in the user interface.
Directory | Directory layout for the application.
DrLocator | For file searches using the directory tree.
DuplicateFile | Lists files to be duplicated.
Environment | Lists the environment variables.
Error | Lists error message formatting templates.
EventMapping | Lists the events subscribed to by controls.
Extension | File extension server information.
Feature | Defines the logical tree structure of features.
FeatureComponents | Defines features and component relationships.
File | Complete list of source files with their attributes.
FileSFPCatalog | Associates specified files with the catalog files used by Windows Millennium Edition for Windows File Protection.
Font | Registry information for font files.
Icon | Contains the icon files.
IniFile | Information needed to set in an .ini file.
IniLocator | Searches for file or directory using an .ini file.
InstallExecuteSequence | Lists INSTALL actions in sequence.
InstallUISequence | Lists UI INSTALL actions in sequence.
IsolatedComponent | Lists Isolated Components.
LaunchCondition | Lists conditions for the installation to begin.
ListBox | Lists the values for all list boxes.
ListView | Lists the values for all listviews.
LockPermissions | Defines locked-down portions of the application.
Media | Lists source media disks for the installation.
MIME | Lists MIME content type, file extension, or CLSID.
MoveFile | Lists files to be moved or copied.
MsiDigitalCertificate | Stores certificates in binary stream format and associates each certificate with a primary key. Available with Windows Installer version 1.5 and later.
MsiDigitalSignature | Contains the signature information for every digitally signed object in the installation database. Available with Windows Installer version 1.5 and later.
MsiFileHash | Stores a 128-bit hash of source files provided by the Windows Installer package.
ODBCAttribute | Lists attributes of ODBC drivers and translators.
ODBCDataSource | Lists data sources belonging to the installation.
ODBCDriver | Lists ODBC drivers belonging to the installation.
ODBCSourceAttribute | Lists the attributes of data sources.
ODBCTranslator | Lists ODBC translators of the installation.
Patch | Lists files that are to receive a particular patch.
PatchPackage | Lists all patch packages applied to this product.
ProgId | Information for program IDs.
Property | Property names and values for all properties.
PublishComponent | Information used for component publishing.
RadioButton | Lists buttons for all the radio button groups.
Registry | Registry information for the application.
RegLocator | Searches for file or directory using the registry.
RemoveFile | Lists files to be removed by RemoveFiles action.
RemoveIniFile | Information needed to delete from an .ini file.
RemoveRegistry | Information needed to delete from system registry.
ReserveCost | Reserves disk space in any directory conditionally.
SelfReg | Information about self-registered modules.
ServiceControl | Controls installed or uninstalled services.
ServiceInstall | Information used to install a service.
SFPCatalog | The catalogs used by Windows Millennium Edition for Windows File Protection on Windows Millennium Edition.
Shortcut | Information needed to create shortcuts.
Signature | Lists the unique file signatures that identify files.
TextStyle | Specifies the text styles used in the text controls.
TypeLib | Registry information for type libraries.
UIText | Localized versions of some strings used in the user interface.
Verb | Command-verb information for file extensions.
_Validation | Column names and values for all tables.
_Columns | Read-only column catalog.
_Streams | Lists embedded OLE data streams.
_Storages | Lists embedded OLE substorages.
_Tables | Read-only system table listing all the tables.
_TransformView Table | A read-only temporary table used to view transforms.
Upgrade | Information used in an upgrade of an application.


Column Data Types

The columns of the database tables are formatted in one of the following data types:

  • Text
  • UpperCase
  • LowerCase
  • Integer
  • DoubleInteger
  • Time/Date
  • Identifier
  • Property
  • Filename
  • WildCardFilename
  • Path
  • Paths
  • AnyPath
  • DefaultDir
  • RegPath
  • Formatted
  • Template
  • Condition
  • GUID
  • Version
  • Language
  • Binary
  • CustomSource
  • Cabinet
  • Shortcut


Text

The Text data type is a text string. It is not validated.


UpperCase

The UpperCase data type is a text string that must be all uppercase.


LowerCase

The LowerCase data type is a text string that must be all lowercase.


Integer

The Integer data type is a two-byte integer value. Unless otherwise restricted, the range of legal values is from –32,767 to +32,767.


DoubleInteger

The DoubleInteger data type is a four-byte integer value. Unless otherwise restricted, the range of legal values is from –2,147,483,647 to +2,147,483,647.


Time/Date

The Time/Date data type has the time and the date stored individually, using unsigned integers as bit fields, packed as follows.

Time

Time is encoded in an unsigned 2-byte integer with the following bit fields.

Contents | Bits | Value range
hours | 0 1 2 3 4 | 0–23
minutes | 5 6 7 8 9 A | 0–59
2-second intervals | B C D E F | 0–29

Date

Date is encoded in an unsigned 2-byte integer with the following bit fields.

Contents | Bits | Value range
year | 0 1 2 3 4 5 6 | 0–119 (relative to 1980)
month | 7 8 9 A | 1–12
day | B C D E F | 1–31


Identifier

The Identifier data type is a text string. Identifiers may contain ASCII characters, digits, underscores (_), or periods (.). However, every identifier must begin with either a letter or an underscore.


Property

The Property data type is a valid Identifier with the additional syntax "%identifier", which represents an environment variable.


Filename

The Filename data type is a text string containing a file name or folder. By default, the file name is assumed to use short file name syntax; that is, eight-character name, period (.), and 3-character extension. A short file name must always be provided because the SHORTFILENAMES property may be set or the target volume for the installation may only support short file names.

To include a long file name with the short file name, separate it from the short file name with a vertical bar (|). For example, the following two strings are valid:

status.txt
projec~1.txt|Project Status.txt

Short and long file names must not contain the following characters:

\   ?   |   >  <   :  /  *  "

In addition, short file names must not contain the following characters:

+  ,  ;  =  [  ]

Short file names may not include a space, although a long file name may. No space is allowed preceding the vertical bar (|) separator for the short file name/long file name syntax. If a space exists after the separator, then the long file name must have a space at the beginning of the file name. No full-path syntax is allowed.


WildCardFilename

The WildCardFilename data type is a Filename that may also contain the wild card characters "?" for any single character or "*" for zero or more occurrences of any character.


Path

The Path data type is a text string containing a valid full path.

The string may also contain a property name enclosed in square brackets [ ]. In such a case, the name of the property, including the brackets, is replaced in the string by the value of the property.

The following restriction applies to Windows Installer version 1.0 only:

  • The property name and brackets may not be preceded or succeeded by any alphabetic characters. For example, "\\server\share\[username]" is valid, but "\\server\share\abc[username]" is not.

Examples:

  • UNC path: \\server\share
  • Local drive: c:\temp
  • With a property name: [DRIVE]\temp


Paths

The Paths data type is a text string containing a list of Path data types, separated by semicolons (;).


AnyPath

The AnyPath data type is a text string containing either a full path or a relative path. When specifying a relative path, you can include a long file name with the short file name by separating the short and long names with a vertical bar (|). Note that you cannot specify multiple levels of a directory or fully qualified paths in this way. The path may contain properties enclosed within square brackets ([ ]).

Examples of valid AnyPath data:

  • \\server\share\temp
  • c:\temp
  • \temp
  • projec~1|Project Status

Examples of invalid AnyPath data:

  • c:\temp\projec~1|c:\temp one\Project Status
  • \temp\projec~1|\temp one\Project Status


DefaultDir

The DefaultDir data type is a text string containing either a valid Filename or a valid Identifier. This is used only in the Directory table. It must be an identifier if the directory is a root directory. If the directory is a non-root, this value must be a filename or a filename:filename pair. Note that "." is allowed as a file name and has special meaning in the Directory table.


RegPath

The RegPath data type is a text string containing a Registry path. Registry paths can include properties, as with the Formatted data type. A RegPath may not begin or end with a backslash (\). The [#file key] and [$component key] can be embedded in the path or preceded by other characters.


Formatted

The Formatted data type is a text string that is processed to resolve embedded property names, table keys, environment variable references, and other special substrings. The following conventions are recognized to resolve the string:

  • Square brackets ([ ]) or curly braces ({ }) with no matching pair are left in the text.
  • If a substring of the form [propertyname] is encountered, it is replaced by the value of the property. If propertyname is not a valid property, then the substring is left unchanged.

    The square brackets may be iterated and the property names are resolved from inside out. For example, suppose the substring [[PropertyA]] appears in the text. First, the value of property PropertyA is retrieved. If the value is a valid property name, such as PropertyB, then the value of PropertyB is retrieved, and the entire substring [[PropertyA]] is substituted with the value of PropertyB. If PropertyA is not a valid property name, or if the value of PropertyA is not a valid property name, then the substring is blank.

  • If a substring of the form [%environmentvariable] is found, the value of the environment variable is substituted for the substring.
  • If a substring of the form [\x] is found, it is replaced by the character x , where x is one character, without any further processing. Only the first character after the backslash is kept; everything else is removed.
  • If a substring is enclosed in curly braces ({ }), and it contains no property names enclosed in square brackets ([ ]), the substring is left unchanged, including the curly braces.
  • If a substring is enclosed in curly braces ({ }) and it contains one or more property names enclosed in square brackets ([ ]) then, if all the property names are valid, the text (with the resolved substitutions) is displayed without the curly braces.
  • If a substring of the form [~] is found, it is replaced with the null character. This is used to author REG_MULTI_SZ character strings in the Registry table. Note that [~] is also used to append or prefix values to environment variables using the Environment table.
  • If a substring of the form [#filekey] is found, it is replaced by the full path of the file, with the value filekey used as a key into the File table. The value of [#filekey] remains blank and is not replaced by a path until the installer runs the CostInitialize action, FileCost action, and CostFinalize action. The value of [#filekey] depends upon the installation state of the component to which the file belongs. If the component run from the source, the value is the path to the source location of the file. If the component is run locally, the value is the path to the target location of the file after installation. If the component is absent, the path is blank. For more information about checking the installation state of components, see Checking the Installation of Features, Components, Files.

    • If a substring of the form [$componentkey] is found, it is replaced by the install directory of the component, with the value componentkey used as a key into the Component table. The value of [$componentkey] remains blank and is not replaced by a directory until the installer runs the CostInitialize action, FileCost action, and CostFinalize action. The value of [$componentkey] depends upon the installation state of the component. If the component is run from the source, the value is the source directory of the file. If the component is run locally, the value is the target directory after installation. If the component is absent, the value is left blank. For more information about checking the installation state of components, see Checking the Installation of Features, Components.

  • If a substring of the form [!filekey] is found, it is replaced by the full short path of the file, with the value filekey used as a key into the File table.

    This syntax is valid only when used in the Value column of the Registry or the IniFile tables. When used in other columns this syntax is treated the same as [#filekey] .


Template

The Template data type is a text string that may contain properties that are enclosed in brackets [ ]. The template type allows all of the Formatted type formats, plus [1] where 1 is a number.


Condition

The Condition data type is a text string containing a valid conditional statement that can be evaluated as true or false. For information on the syntax of conditional statements, see Conditional Statement Syntax.


GUID

The GUID data type is a text string representing a Class identifier (ID). COM must be able to convert the string to a valid Class ID. All GUIDs must be authored in uppercase.

The valid format for a GUID is {XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX} where X is a hex digit (0,1,2,3,4,5,6,7,8,9,A,B,C,D,E,F).

Note that utilities such as GUIDGEN can generate GUIDs containing lowercase letters. These must all be changed to uppercase letters before the GUID can be used by the installer as a valid product code, package code, or component code.


Version

The Version data type is a text string containing a valid version string. A version string has the format

xxxxx.xxxxx.xxxxx.xxxxx

where x is a digit.

The maximum acceptable version string is 65535.65535.65535.65535.

The following are examples of valid version strings:

  • 1
  • 1.0
  • 1.00
  • 10.00
  • 1.00.1
  • 1.0.1
  • 1.00.10
  • 1.00.100
  • 1.0.1000.0


Language

The Language data type is a text string containing one or more valid numeric language IDs. If there are two or more language IDs, they must be separated by commas.

The Language data type is a 16-bit value that is the combination of a primary and sublanguage numeric IDs. The Primary LANGID comprises bits 0 thru 9 while the subLanguage ID is bits 10 thru 15. For a list of primary and sub language numeric identifiers, see the Locales topic in the Platform SDK documentation.

For primary language IDs, the range 0x200 to 0x3ff is user definable. The range 0x000 to 0x1ff is reserved for system use. For sublanguage IDs, the range 0x20 to 0x3f is user definable. The range 0x00 to 0x1f is reserved for system use.


Binary

The Binary data type is a binary data stream containing any type of binary data. Examples include a bitmap or executable code.


CustomSource

The CustomSource data type is either a valid Identifier or an external key depending on the Type column of the CustomAction table. It can be an external key into the Binary table, File table, Directory table, and Property table. Note that external keys into the Property Table are not validated because properties can be added at run-time.


Cabinet

The Cabinet data type must be used in the Cabinet column of the Media table

If the cabinet name is preceded by the number sign, the cabinet is stored as a data stream inside the package. The character string which follows the # is an Identifier for this data stream. Note that if the cabinet is stored as a data stream, the name of a cabinet is case-sensitive.

If the cabinet name is not preceded by the number sign #, the cabinet is stored in a separate file located at the root of the source tree specified by the Directory Table. The cabinet file must use the short file name syntax consisting of an eight character name, a period, and a three character extension. The Cabinet data type cannot use the short|longname syntax for file names. If the cabinet file is stored as a separate file, the name of the cabinet file is not case-sensitive.

To conserve disk space, the installer removes any cabinets embedded in the .msi file before caching the installation package on the user's computer.

See Including a Cabinet File in an Installation.


Shortcut

The Shortcut data type is usually used in the Target column of the Shortcut table. If it contains square brackets ([ ]), the shortcut target is evaluated as a Formatted string. Otherwise, the shortcut is evaluated as an Identifier and must be a valid foreign key into the Feature table.


_RowState Column

The reserved column name _RowState represents the non-persistent state associated with each table row in an installer database table. The pseudo-column is of type Integer, and the value consists of a set of bit flags. All the bits are readable, but only the UserInfo and Temporary bits can be set. This data is available only as long as the tables are locked or in use (that is, while a view containing the tables exists). The following table shows the attributes a row can have.

Name | Value | Meaning
iraUserInfo | 0x01 | The attribute is for external use. This value can be updated.
iraTemporary | 0x02 | The row is not persistent. This value can be updated.
iraModified | 0x04 | A row has been updated.
iraInserted | 0x08 | A row has been inserted.
iraMergeFailed | 0x0F | An attempt was made to merge with non-identical, non-key data.

Bits 6 through 8 are reserved.


ActionText Table

The ActionText table contains text to be displayed in a progress dialog box and written to the log for actions that take a long time to execute. The text displayed consists of the action description and optionally formatted data from the action.

The ActionText table has the following columns.

Column | Type | Key | Nullable
Action | Identifier | Y | N
Description | Text |  | Y
Template | Template |  | Y

Columns

Action
Name of the action.

Primary table key.

Description
Localized description displayed in the progress dialog box or written to the log when the action is executing.
Template
A localized format template is used to format action data records for display during action execution. If no template is supplied, then the action data will not be displayed.

Remarks

The entries in the ActionText table typically refer to actions in sequence tables. There are other actions performed by the installer that are not listed in the sequence table but still need to be specified in this table. These required entries are listed below. The action name and template must be authored exactly as shown, but the description may be customized.

Action | Description | Template
Rollback | Undoes actions. | [1]
RollbackCleanup | Removes old files. | [1]
GenerateScript | Generates system operations for action. | [1]


AdminExecuteSequence Table

The AdminExecuteSequence table lists actions that the installer calls in sequence when the top-level ADMIN action is executed.

ADMIN actions in the install sequence, up to the InstallValidate action and any exit dialog boxes, are located in the AdminUISequence table.

ADMIN actions from the InstallValidate action through the end of the install sequence are in the AdminExecuteSequence table. Because the AdminExecuteSequence table needs to stand alone, it also contains any necessary initialization actions such as LaunchConditions, CostInitialize, FileCost, and CostFinalize.

Custom actions requiring a user interface should use MsiProcessMessage instead of authored dialog boxes created using the Dialog table.

The columns are identical to those of the InstallExecuteSequence table. The AdminExecuteSequence table has the following columns.

Column | Type | Key | Nullable
Action | Identifier | Y | N
Condition | Condition |  | Y
Sequence | Integer |  | N

Columns

Action
Name of the action to execute. This is either a standard action or a custom action listed in the CustomAction table.

Primary table key.

Condition
Logical expression. If the expression evaluates to false, the action is skipped. If the expression syntax is invalid, the sequence terminates, returning iesBadActionData. For information on the syntax of conditional statements see Conditional Statement Syntax.
Sequence
A positive value indicates the sequence position of the action. The following negative values indicate that the action is called if the installer returns the termination flag shown in parentheses.
Termination flag | Value | Description
msiDoActionStatusSuccess | -1 | Successful completion.
msiDoActionStatusUserExit | -2 | User terminates install.
msiDoActionStatusFailure | -3 | Fatal exit terminates.
msiDoActionStatusSuspend | -4 | Install is suspended.

Zero, all other negative numbers, or a NULL value indicate that the action is never called.


AdminUISequence Table

The AdminUISequence table lists actions that the installer calls in sequence when the top-level ADMIN action is executed and the internal user interface level is set to full UI or reduced UI. The installer skips the actions in this table if the user interface level is set to basic UI or no UI. See About the User Interface.

ADMIN actions in the install sequence up to the InstallValidate action, and any exit dialog boxes, are located in the AdminUISequence table. All actions from the InstallValidate through the end of the install sequence are in the AdminExecuteSequence table. Because the AdminExecuteSequence table needs to stand alone, it also contains any necessary initialization actions such as LaunchConditions, CostInitialize, FileCost, and CostFinalize. It also has the ExecuteAction action.

The columns are identical to those of the InstallUISequence table. The AdminUISequence table has the following columns.

Column | Type | Key | Nullable
Action | Identifier | Y | N
Condition | Condition |  | Y
Sequence | Integer |  | N

Columns

Action
Name of the action to execute. This is either a standard action, a user interface wizard, or a custom action listed in the CustomAction table.

Primary table key.

Condition
Logical expression. If the expression evaluates to false, the action is skipped. If the expression syntax is invalid, the sequence terminates, returning iesBadActionData. For information on the syntax of conditional statements, see Conditional Statement Syntax.
Sequence
A positive value indicates the sequence position of the action. The following negative values indicate that the action is called if the installer returns the termination flag shown in parentheses.
Termination flag | Value | Description
msiDoActionStatusSuccess | -1 | Successful completion.
msiDoActionStatusUserExit | -2 | User terminates install.
msiDoActionStatusFailure | -3 | Fatal exit terminates.
msiDoActionStatusSuspend | -4 | Install is suspended.

Zero, all other negative numbers, or a NULL value indicate that the action is never called.


AdvtExecuteSequence Table

The AdvtExecuteSequence table lists actions the installer calls when the top-level ADVERTISE action is executed.

Only the following actions can be used in the AdvtExecuteSequence table. Custom actions cannot be used in this table.

CostFinalize

CostInitialize

CreateShortcuts

InstallFinalize

InstallInitialize

InstallValidate

PublishComponents

PublishFeatures

PublishProduct

RegisterClassInfo

RegisterExtensionInfo

RegisterMIMEInfo

RegisterProgIdInfo

The columns are identical to those of the InstallExecuteSequence table. The AdvtExecuteSequence table has the following columns.

Column | Type | Key | Nullable
Action | Identifier | Y | N
Condition | Condition |  | Y
Sequence | Integer |  | N

Columns

Action
Name of the standard action the installer is to execute. This is the primary key of the table.
Condition
Logical expression. If the expression evaluates to false, the action is skipped. If the expression syntax is invalid, the sequence terminates, returning iesBadActionData. For information on the syntax of conditional statements, see Conditional Statement Syntax.
Sequence
A positive value indicates the sequence position of the action. The following negative values indicate that the action is called if the installer returns the termination flag shown in parentheses.
Termination flag | Value | Description
msiDoActionStatusSuccess | -1 | Successful completion.
msiDoActionStatusUserExit | -2 | User terminates install.
msiDoActionStatusFailure | -3 | Fatal exit terminates.
msiDoActionStatusSuspend | -4 | Install is suspended.

Zero, all other negative numbers, or a NULL value indicate that the action is never called.


AdvtUISequence Table

The installer does not use this table. The AdvtUISequence table should not exist in the installation database or it should be left empty.


AppId Table

The AppId table or the Registry table specifies that the installer configure and register DCOM servers to do one of the following during an installation.

  • Run the DCOM server under a different identity than the user activating the server. For example, to configure a DCOM server to always run as an interactive user or as a predefined user.
  • Run the DCOM server as a service.
  • Configure the default security access for the DCOM server.
  • Register the DCOM server such that it is activated on a different computer.

This table is processed at the installation of the component associated with the DCOM server in the _Component column of the Class table. An AppId is not advertised.

The AppId table has the following columns.

Column | Type | Key | Nullable
AppId | GUID | Y | N
RemoteServerName | Formatted |  | Y
LocalService | Text |  | Y
ServiceParameters | Text |  | Y
DllSurrogate | Text |  | Y
ActivateAtStorage | Integer |  | Y
RunAsInteractiveUser | Integer |  | Y

Columns

AppId
The AppId column of the Class table is a foreign key into this column of the AppId table. This column contains the AppId value that will be written under the CLSID and creates the AppId GUID key under HKCR\AppId.
RemoteServerName
This column contains the value of "RemoteServerName"=<xxxx> that will be written under HKCR\AppID\{AppID}\ .
LocalService
This column contains the value of LocalService that will be written under HKCR\AppID\{<appid>} "LocalService"=<xxx>.
ServiceParameters
This column contains the value of ServiceParameters that will be written under HKCR\AppID\{appid>} "ServiceParameters".
DllSurrogate
This column contains the value of DllSurrogate that will be written under HKCR\AppId\{<appid>} "DllSurrogate"=<xxx>. If this column is present it will typically be an empty string.
ActivateAtStorage
This column contains the value of ActivateAtStorage that will be written under HKCR\AppID\{<appid>} "ActivateAtStorage"="Y".
RunAsInteractiveUser
This column contains the value of RunAsInteractiveUser that will be written under HKCR\AppID\{appid>} "RunAs"="Interactive User".

Remarks

This table is used by the RegisterClassInfo action and UnregisterClassInfo action.

Note that the AppId table does not have a column for registering a Default name. Therefore in cases where you need to write a user friendly name as the Default name value, you must register using the Registry table.


AppSearch Table

The AppSearch table contains properties needed to search for a file having a particular file signature. The AppSearch table can also be used to set a property to the existing value of an registry or .ini file entry.

The AppSearch table has the following columns.

Column | Type | Key | Nullable
Property | Identifier | Y | N
Signature_ | Identifier | Y | N

Columns

Property
Running the AppSearch action sets this property to the location of the file indicated by the Signature_ column. This property is set if the file signature exists on the user's computer. The properties used in this column must be public properties and have an identifier that contains no lowercase letters.

The property listed in the Property field may be initialized in the Property table or from a command line. If the property is initialized in the Property table, the AppSearch action searches the user's computer for the file's signature. If the AppSearch action locates the signature, the installer sets the property to the found value and overrides the initial value specified in the Property table. If the AppSearch action does not locate the signature, the installer sets the property to the initial value entered in the Property table. If the property is initialized from a command line, the AppSearch action does not search for the signature and the installer always uses the value entered from the command line.

Signature_
The Signature_ column contains a unique identifier called a signature and is also an external key into the RegLocator, IniLocator, CompLocator, and DrLocator tables. When searching for a file the value in this column must also be a foreign key into the Signature table. If value in this column is not listed in the Signature table, the installer determines that the search is for a directory.

Remarks

This table is used by the AppSearch action. The AppSearch action searches for signatures using the CompLocator table first, the RegLocator table next, then the IniLocator table, and finally the DrLocator table. File signatures are listed in the Signature table. A signature that is not in the Signature table denotes a directory and the action sets the property to the directory path for that signature.

See Searching for Existing Applications, Files, Registry Entries or .ini File Entries.


MsiAssembly Table

The MsiAssembly table specifies Windows Installer settings for .NET Framework assemblies and Win32® assemblies.

The MsiAssembly table has the following columns.

Column | Type | Key | Nullable
Component_ | Identifier | Y | N
Feature_ | Identifier |  | N
File_Manifest | Identifier |  | Y
File_Application | Identifier |  | Y
Attributes | Integer |  | N

Columns

Component_
Key into the Component table specifying the Windows Installer component that contains this assembly.
Feature_
Key into the Feature table. When the assembly has to be faulted-in, the Windows Installer installs the feature pointed to by this field.
File_Manifest
An external key into the File table specifying the file that contains the manifest for a .NET Framework assembly.
File_Application
Enter a value in this field to install a .NET Framework or Win32 assembly for the private use of a particular application. The value in this field is an external key into the File table. The installer uses the directory structure specified in the Directory table to install the assembly into the same directory as the component containing this file. This field must be Null if the assembly is to be installed into the global assembly cache.
Attributes
Enter a value of 1 for a Win32 assembly and a value of 0 for a .NET Framework assembly.


MsiAssemblyName Table

The MsiAssemblyName table specifies the schema for the elements of a strong assembly cache name for a .NET Framework or Win32 assembly. The name is constructed by appending all elements with the same Component_ key. See the following example.

The MsiAssemblyName table has the following columns.

Column | Type | Key | Nullable
Component_ | Identifier | Y | N
Name | Text | Y | N
Value | Text |  | Y

Columns

Component_
Key into the Component table specifying the Windows Installer component that contains this assembly.
Name
Name associated with the value specified in the Value column.
Value
Value associated with the name specified in the Name column.

Remarks

For example, the MsiAssemblyName table may specify that an assembly have a strong name with the following schema.

Component | Name | Value
ComponentA | name | SingleAssembly
ComponentA | ver | 1.2.3.4
ComponentA | SN | SimpleName


BBControl Table

The BBControl table lists the controls to be displayed on each billboard.

The BBControl table has the following columns.

Column | Type | Key | Nullable
Billboard_ | Identifier | Y | N
BBControl | Identifier | Y | N
Type | Identifier |  | N
X | Integer |  | N
Y | Integer |  | N
Width | Integer |  | N
Height | Integer |  | N
Attributes | DoubleInteger |  | Y
Text | Text |  | Y

Columns

Billboard_
Name of the billboard.

External key to column one of the Billboard table.

BBControl
Name of the control. This name must be unique within a billboard but can be repeated on different billboards. This column combined with the Billboard_ column forms the primary key to the table.
Type
The type of the control. Only static controls, such as a Text, Bitmap, Icon, or custom control can be placed on a billboard. For a complete list of controls, see the Controls section.
X
Horizontal coordinate of the upper-left corner of the rectangular boundary of the control. The units are installer units. This coordinate is measured relative to the billboard control and not relative to the dialog. Use only non-negative numbers.
Y
Vertical coordinate of the upper-left corner of the rectangular boundary of the control. The units are installer units. This coordinate is measured relative to the billboard control and not relative to the dialog. This number must be non-negative.
Width
Width of the rectangular boundary of the control. The units are installer units. This number must be non-negative.
Height
Height of the rectangular boundary of the control. The units are installer units. This number must be non-negative.
Attributes
A 32-bit word specifying the attribute flags to be applied to this control. This number must be non-negative and specify an attribute for a static control that is valid for placement on a billboard. For information on the numeric values to enter into this field, see the particular attribute under Control Attributes.
Text
This column contains a localizable string used to set the initial text in the control if the control displays text. The string is truncated if the text is too long to fit on the control. This column contains a key into the Binary table if the control is a push button or a check box containing an icon or bitmap. It is not possible to show both text and a picture on the same button. This column may be left blank.

Remarks

The integer values for x, y, width, and height are in the installer units, not dialog units. An installer unit is equal to one-twelfth the height of the 10-point MS Sans Serif font size. Coordinates for the controls are relative to the billboard control not the dialog.


Billboard Table

The Billboard table lists the billboards displayed in the full user interface. A billboard is a part of a dialog that dynamically changes on progress or through action data messages.

The Billboard table has the following columns.

Column | Type | Key | Nullable
Billboard | Text | Y | N
Feature_ | Identifier |  | N
Action | Identifier |  | Y
Ordering | Integer |  | Y

Columns

Billboard
Name of the billboard.
Feature_
An external key to the first column of the Feature table. The billboard is displayed only if this feature is being installed.
Action
The name of an action. The billboard is displayed during the progress messages received from this action.
Ordering
If there is more than one billboard corresponding to an action, then they are displayed in the order defined by this column. This number must be non-negative.


Binary Table

The Binary table holds the binary data for items such as bitmaps, animations, and icons. The binary table is also used to store data for custom actions. See OLE Limitations on Streams.

The Binary table has the following columns.

Column | Type | Key | Nullable
Name | Identifier | Y | N
Data | Binary |  | N

Columns

Name
A unique key that identifies the particular binary data. If the binary data is for a control, the key appears in the Text column of the associated control in the Control table. This key must be unique among all controls requiring binary data.
Data
The unformatted binary data.


BindImage Table

The BindImage table contains information about each executable or DLL that needs to be bound to the DLLs imported by it.

The BindImage table has the following columns.

Column | Type | Key | Nullable
File_ | Identifier | Y | N
Path | Paths |  | Y

Columns

File_
An external key to column one of the File table. This must be an executable file or a DLL file.
Path
A list of paths, separated by semicolons, that represent the paths to be searched to find the imported DLLs. The list is usually a list of properties, with each property enclosed inside square brackets ([ ]) .

Remarks

The installer computes the virtual address of each function that is imported from all DLLs, and the computed virtual address is then saved in the importing image's Import Address Table (IAT).

This table is referred to when the BindImage action is executed.


CCPSearch Table

The CCPSearch table contains the list of file signatures used for the Compliance Checking Program (CCP). At least one of these files needs to be present on a user's computer for the user to be in compliance with the program.

The CCPSearch table has the following column.

Column | Type | Key | Nullable
Signature_ | Identifier | Y | N

Column

Signature_
The Signature_ represents a unique file signature and is also the external key into the Signature, RegLocator, IniLocator, CompLocator, and DrLocator tables.

Remarks

This table is referred to when the CCPSearch action or the RMCCPSearch action is executed.


CheckBox Table

The CheckBox table lists the values for the check boxes.

The CheckBox table has the following columns.

Column | Type | Key | Nullable
Property | Identifier | Y | N
Value | Formatted |  | Y

Columns

Property
A named property to be tied to this item.
Value
The value string associated with this item.

Remarks

If the check box is selected, then the corresponding property is set to the specified value. If there is no value specified or this table does not exist, then the property is set to its original value when the check box is selected. If the original value is NULL, the property is set to "1".

The contents of the Value column are formatted by the MsiFormatRecord function when the control is created. Therefore, it can contain any expression that the MsiFormatRecord function can interpret. The Value column is formatted only when the control is created, and it is not updated if a property involved in an expression is modified during the life of the control.


Class Table

The Class table contains COM server-related information that must be generated as a part of the product advertisement. Each row may generate a set of registry keys and values. The associated ProgId information is included in this table.

The Class table has the following columns.

Column | Type | Key | Nullable
CLSID | GUID | Y | N
Context | Identifier | Y | N
Component_ | Identifier | Y | N
ProgId_Default | Text |  | Y
Description | Text |  | Y
AppId_ | GUID |  | Y
FileTypeMask | Text |  | Y
Icon_ | Identifier |  | Y
IconIndex | Integer |  | Y
DefInprocHandler | Filename |  | Y
Argument | Formatted |  | Y
Feature_ | Identifier |  | N
Attributes | Integer |  | Y

Columns

CLSID
The Class identifier (ID) of a COM server.
Context
The server context for this server.

This may be one of the following values:

LocalServer

LocalServer32

InprocServer

InprocServer32

Component_
External key into the Component table specifying the component whose key file provides the COM server.
ProgId_Default
The default Program ID associated with this Class ID. This column is a foreign key into the ProgID table.
Description
Localized description associated with the Class ID and Program ID.
AppId_
Application ID containing DCOM information for the associated application (string GUID). This column is a foreign key into the AppId table.
FileTypeMask
Contains information for the HKCR (this CLSID) key.

If multiple patterns exist, they must be delimited by a semicolon, and numeric subkeys are generated: 0, 1, 2... For more information about this functionality, see GetClassFile.

Icon_
The file providing the icon associated with this CLSID. The installer writes the entry in this column under the DefaultIcon key associated with the ProgId. If it is not null, the column is a foreign key into the Icon table. If it is null, the COM server provides the icon resource. Advertised file associations and shortcuts require a non-null value in this column to display properly.
IconIndex
Icon index into the icon file. This can be NULL.

Non-negative numbers only.

DefInprocHandler
Default inproc handler.

May be optionally provided only for Context = LocalServer or LocalServer32. A non-numeric value is treated as a system file that serves as the 32-bit InprocHandler (appearing as the InprocHandler32 value).
Value | Meaning
1 = default (system) | 16-bit InprocHandler (appearing as the InprocHandler value)
2 = default (system) | 32-bit InprocHandler (appearing as the InprocHandler32 value)
3 = default (system) | 16-bit as well as 32-bit InprocHandlers

Argument
This column is optional only when the Context column is set to the LocalServer or LocalServer32 server context. The text is registered as the argument against the OLE server and is used by OLE for invoking the server.

Note that the resolution of properties in the Argument field is limited. A property formatted as [Property] in this field can only be resolved if the property already has the intended value when the component owning the class is installed. For example, for the argument "[#MyDoc.doc]" to resolve to the correct value, the same process must be installing the file MyDoc.doc and the component that owns the class.

Feature_
External key into the Feature table specifying the feature that provides the COM server.

External key to column one of the Feature table.

Attributes
If msidbClassAttributesRelativePath is set in this column, the bare file name can be used for COM servers. The installer registers the file name only instead of the complete path. This enables the server in the current directory to take precedence and allows multiple copies of the same component. This is available in Windows Installer version 1.1.
Attribute | Decimal | Hexadecimal
msidbClassAttributesRelativePath | 1 | 0x001

Remarks

This table is referred to when the RegisterClassInfo action or the UnregisterClassInfo action is executed.


ComboBox Table

The lines of a combo box are not treated as individual controls; they are part of a single combo box that functions as a control. This table lists the values for each combo box.

The ComboBox table has the following columns.

Column | Type | Key | Nullable
Property | Identifier | Y | N
Order | Integer | Y | N
Value | Formatted |  | N
Text | Text |  | Y

Columns

Property
A named property to be tied to this item. All the items tied to the same property become part of the same combo box.
Order
A positive integer used to determine the ordering of the items that appear in a single combo box list. The integers do not have to be consecutive. If a combo box is defined as ordered, then all the items should have an Order value. If the combo box is defined as unordered, then this column is ignored.

Positive numbers only.

Value
The value string associated with this item. Selecting this line of the combo box sets the associated property (specified in Property) to this value.
Text
The visible, localizable text to be assigned to the item. If this entry or the entire column is missing, then the text defaults to the entry in Value.

Remarks

The contents of the Value and Text fields are formatted by the MsiFormatRecord function when the control is created, therefore they can contain any expression that the MsiFormatRecord function can interpret. The formatting occurs only when the control is created and it is not updated if a property involved in the expression is modified during the life of the control.


CompLocator Table

The CompLocator table holds the information needed to find a file or a directory using the installer configuration data.

The CompLocator table has the following columns.

Column | Type | Key | Nullable
Signature_ | Identifier | Y | N
ComponentId | GUID |  | N
Type | Integer |  | Y

Columns

Signature_
This column represents a unique file signature and is also the external key into the Signature table. If the key is absent from the Signature table, the search is assumed to be for the presence of a directory pointed to by the CompLocator Table.
ComponentId
The component ID of the component whose key path is to be used for the search.
Type
A Boolean value that determines if the key path of the component is a file name or a directory location.

The following table lists valid values. If absent, Type is set to be 1.
Constant | Hexadecimal | Decimal | Description
msidbLocatorTypeDirectory | 0x000 | 0 | Key path is a directory.
msidbLocatorTypeFileName | 0x001 | 1 | Key path is a file name.

Remarks

This table is used with the AppSearch Table.

This table's columns are generally not localized. If an author decides to search for products in multiple languages, then there can be a separate entry included in the table for each language.

See Searching for Existing Applications, Files, Registry Entries or .ini File Entries.


Complus Table

The Complus table contains information needed to install COM+ applications.

The Complus table has the following columns.

Column | Type | Key | Nullable
Component_ | Identifier | Y | N
ExpType | Integer |  | Y

Columns

Component_
An external key into the first column of the Component table. This is the component that contains the COM+ application.
ExpType
Export flags used during the generation of the .msi file. For more information see the COM+ documentation in the Platform SDK.

Remarks

This table is not available in Windows Installer version 1.0.

See the RegisterComPlus action and UnregisterComPlus action.

See How do I install a COM+ application with the Windows Installer?.


Component Table

The Component table lists components and it has the following columns.

Column | Type | Key | Nullable
Component | Identifier | Y | N
ComponentId | GUID |  | Y
Directory_ | Identifier |  | N
Attributes | Integer |  | N
Condition | Condition |  | Y
KeyPath | Identifier |  | Y

Columns

Component
Identifies the component record.

Primary table key.

ComponentId
A string GUID unique to this component, version, and language.

Note that the letters of these GUIDs must be uppercase. Utilities such as GUIDGEN can generate GUIDs containing lowercase letters. The lowercase letters must be changed to uppercase to make these valid component code GUIDs.

If this column is null the installer does not register the component and the component cannot be removed or repaired by the installer. This might be intentionally done if the component is only needed during the installation, such as a custom action that cleans up temporary files or removes an old product. It may also be useful when copying data files to a user's computer that do not need to be registered.

Directory_
External key of an entry in the Directory table. This is a property name whose value contains the actual path, which can be set either by the AppSearch action or with the default setting obtained from the Directory table.

Developers must avoid authoring components that place files into one of the User Profile folders. These files would not be available to all users in multi-user situations and could cause the installer to permanently view the component as requiring repair.

External key to column one of the Directory table.

Attributes
This column contains a bit flag that specifies options for remote execution. Add the indicated bit to the total value in the column to include an option.
Bit flag name | Decimal | Hexadecimal | Remote execution option
msidbComponentAttributesLocalOnly | 0 | 0x0000 | Component cannot be run from source.
msidbComponentAttributesSourceOnly | 1 | 0x0001 | Component can only be run from source.
msidbComponentAttributesOptional | 2 | 0x0002 | Component can run locally or from source.
msidbComponentAttributesRegistryKeyPath 4 0x0004 If this bit is set, the value in the KeyPath column is used as a key into the Registry table.

In this case, the Value and Name fields of the corresponding Registry table record cannot be left blank. They must either specify a registry value and registry value name, or if Null, contain "+", "-", or "*". See the Registry table.

Setting this bit is recommended for registry entries written to the HKCU hive. This ensures the installer writes the necessary HKCU registry entries when there are multiple users on the same machine.
msidbComponentAttributesSharedDllRefCount | 8 | 0x0008 | If this bit is set, the installer increments the reference count in the shared DLL registry of the component's key file. If this bit is not set, the installer increments the reference count only if the reference count already exists.
msidbComponentAttributesPermanent | 16 | 0x0010 | If this bit is set, the installer does not remove the component during an uninstall. The installer registers an extra system client for the component in the Windows Installer registry settings.
msidbComponentAttributesODBCDataSource | 32 | 0x0020 | If this bit is set, the value in the KeyPath column is a key into the ODBCDataSource table.
msidbComponentAttributesTransitive 64 0x0040 If this bit is set, the installer reevaluates the value of the statement in the Condition column upon a reinstall. If the value was previously False and has changed to True, the installer installs the component. If the value was previously True and has changed to False, the installer removes the component even if the component has other products as clients.

This bit should only be set for transitive components. See Using Transitive Components.
msidbComponentAttributesNeverOverwrite 128 0x0080 If this bit is set, the installer does not install or reinstall the component if a key path file or a key path registry entry for the component already exists. The application does register itself as a client of the component.

Use this flag only for components that are being registered by the Registry table. Do not use this flag for components registered by the AppId, Class, Extension, ProgId, MIME, and Verb tables.
msidbComponentAttributes64bit 256 0x0100 Set this bit to mark this as a 64-bit component. This attribute facilitates the installation of packages that include both 32-bit and 64-bit components. If this bit is not set, the component is registered as a 32-bit component.

If this is a 64-bit component replacing a 32-bit component, set this bit and assign a new GUID in the ComponentId column.

Condition
This column contains a conditional statement that can control whether a component is installed. If the condition is null or evaluates to true, then the component is enabled. If the condition evaluates to False, then the component is disabled and is not installed.

The Condition field enables or disables a component only during the CostFinalize action. To enable or disable a component after CostFinalize, you must use a custom action or the DoAction ControlEvent to call MsiSetComponentState.

Note that unless the Transitive bit in the Attributes column is set for a component, the component remains enabled once installed even if the conditional statement in the Condition column later evaluates to False on a subsequent maintenance installation of the product.

The Condition column in the Component table accepts conditional expressions containing references to the installed states of features and components. For information on the syntax of conditional statements, see Conditional Statement Syntax.

KeyPath
This value points to a file or folder belonging to the component that the installer uses to detect the component. Two components can not share the same key path value. The value in this column is also the path returned by the MsiGetComponentPath function.

If the value is not NULL, then KeyPath is either a primary key into the Registry, ODBCDataSource, or File tables depending upon the Attribute value. If KeyPath is null, then the folder of the Directory_ column is used as the key path.

Because folders created by the installer are deleted when they become empty, you must author an entry into the CreateFolder table to install a component that consists of an empty folder.

Remarks

For a discussion of the relationship between components and features, see Feature Table.

The installer keeps track of shared DLLs independently of the shared DLL reference count in the registry. If a reference count for a shared DLL exists in the registry, the installer always increments the count when it is installing the file and decrements it when it is uninstalling. If msidbComponentAttributesSharedDllRefCount, is not set, and the reference count does not already exist, the installer will not create one. Note that the SharedDLLs reference count in the registry is incremented for any files installed to the System folder (System32 on Windows NT/Windows 2000).

If msidbComponentAttributesSharedDllRefCount is not set, then another application can remove the component even if it is still needed. To see how this could happen consider the following scenario:

  • An application that uses the installer installs a shared component.
  • The msidbComponentAttributesSharedDllRefCount bit is not set and there is no reference count. Thus the installer does not begin a reference count.
  • A legacy application that shares this component and does not use the installer is installed.
  • The legacy application creates and increments a reference count for the shared component.
  • The legacy application is uninstalled.
  • The reference count for the shared component is decremented to zero and the component is removed.
  • The application using the installer no longer has access to the component.

To avoid this behavior, set msidbComponentAttributesSharedDllRefCount.

Note that system services components should not be specified as run-from-source without being specifically designed for such use. See the ServiceInstall table for more details.

Note that attributes enabling run-from-source installation should never be set for components containing dynamic-link libraries that are going into the system folder. The reason is that if the installation state of the component becomes set to run-from-source by following a feature or by being set in the UI, subsequent calls to LoadLibrary on the DLL would fail.


Condition Table

The Condition table can be used to modify the selection state of any entry in the Feature table based on a conditional expression.

The Condition table has the following columns.

Column | Type | Key | Nullable
Feature_ | Identifier | Y | N
Level | Integer | Y | N
Condition | Condition |  | Y

Columns

Feature_
External key into column one of the Feature table.
Level
A conditional install level for the feature in the Feature_ column of this table. The installer sets the install level of this feature to the level specified in this column if the expression in the Condition column evaluates to TRUE.
Condition
If this conditional expression evaluates to TRUE, then the Level column in the Feature table is set to the conditional install level.

The expression in the Condition column should not contain reference to the installed state of any feature or component. This is because the expressions in the Condition column are evaluated before the installer evaluates the installed states of features and components. Any expression in the Condition table that attempts to check the installed state of a feature or component always evaluates to false.

For information on the syntax of conditional statements, see Conditional Statement Syntax.

Remarks

A feature can be permanently disabled by setting the Level column to 0.

The Level may be set based on any conditional statement, such as a test for platform, operating system, or a particular property setting.

This table is referred to when the CostFinalize action is executed.


Control Table

The Control table defines the controls that appear on each dialog box.

The Control table has the following columns.

Column | Type | Key | Nullable
Dialog_ | Identifier | Y | N
Control | Identifier | Y | N
Type | Identifier |  | N
X | Integer |  | N
Y | Integer |  | N
Width | Integer |  | N
Height | Integer |  | N
Attributes | DoubleInteger |  | Y
Property | Identifier |  | Y
Text | Formatted |  | Y
Control_Next | Identifier |  | Y
Help | Text |  | Y

Columns

Dialog_
External key to the first column of the Dialog table, the name of the dialog box.
Control
Name of the control. This name must be unique within a dialog box but can be repeated on different dialog boxes. The Control column combined with the Dialog_ column form the primary key to this table.
Type
The type of the control. For a list of control types, see Controls.
X
Horizontal coordinate of the upper-left corner of the rectangular boundary of the control. This must be a non-negative number. See Position Control Attribute.
Y
Vertical coordinate of the upper-left corner of the rectangular boundary of the control. This must be a non-negative number. See Position Control Attribute.
Width
Width of the rectangular boundary of the control. This must be a non-negative number. See Position Control Attribute.
Height
Height of the rectangular boundary of the control. This must be a non-negative number. See Position Control Attribute.
Attributes
A 32-bit word that specifies the bit flags to be applied to this control. This must be a non-negative number, and the allowed values depend upon the type of control. For a list of all control attributes, and the value to enter in this field, see Control Attributes.
Property
The name of a defined property to be linked to this control. Radio button, list box, and combo box values are tied into a group by being linked to the same property. This column is required for active controls and is ignored by static controls.
Text
A localizable string used to set the initial text contained in a control. The string can also contain embedded properties. For the syntax of a formatted string containing properties see the MsiFormatRecord function. Specify the size, font, and color of the text by prefixing the text string with {\style}, where style is a text style authored into the TextStyle column of the TextStyle table. The text string is truncated if it is too long to fit on to the control. The text string may be blank.

You can enter a short descriptive text string for the VolumeCostList, ListView, DirectoryList, and the SelectionTree controls. This text is not seen by the user but it can be read by screen readers as the description of the control.

See also Accessibility.

Control_Next
The name of another control on the same dialog box and an external key to the second column of the Control table. If the focus in the dialog box is on the control in the Control column, hitting the tab key moves the focus to the control listed in the Control_Next column. Therefore this column is used to specify the tab order of the controls on the dialog box. The links between the controls must form a closed cycle. Some controls, such as static text controls, can be left out of the cycle. In this case, this field may be left blank.

See also Accessibility.

Help
Optional, localizable text strings that are used with the Help button. The string is divided into two parts by a separator character (|). The first part of the string is used as ToolTip text. This text is used by screen readers for controls that contain a picture. The second part of the string is used for context-sensitive Help. Context-sensitive help is not yet implemented. The separator character is required even if only one of the two kinds of text is present.

Remarks

The integer values for x, y, width, and height are in the installer units, not dialog units. An installer unit is equal to one-twelfth the height of the 10-point MS Sans Serif font size. Coordinates for the controls are relative to the billboard.


ControlCondition Table

The ControlCondition table enables an author to specify special actions to be applied to controls based on the result of a conditional statement. For example, using this table the author could choose to hide a control based on the VersionNT property.

The ControlCondition table has the following columns.

Column | Type | Key | Nullable
Dialog_ | Identifier | Y | N
Control_ | Identifier | Y | N
Action | Text | Y | N
Condition | Condition | Y | N

Columns

Dialog_
An external key to the first column of the Dialog table. Combining this field with the Control_ field identifies a unique control.
Control_
An external key to the second column of the Control table. Combining this field the Dialog_ field identifies a unique control.
Action
The action that is to be taken on the control. The possible actions are shown in the following table.
Value | Meaning
Default | Set control as the default.
Disable | Disable the control.
Enable | Enable the control.
Hide | Hide the control.
Show | Display the control.

Condition
A conditional statement that specifies under which conditions the action should be triggered. This column may not be left blank. If this statement does not evaluate to TRUE, the action does not take place. If it is set to 1, the action is always applied. For information on the syntax of conditional statements, see Conditional Statement Syntax.


ControlEvent Table

The ControlEvent table allows the author to specify what happens when the user interacts with any control within a dialog box. For example, a click of a push button can be defined to trigger a transition to another dialog box, to exit a dialog box sequence, or to begin file installation.

The ControlEvent table has the following columns.

Column | Type | Key | Nullable
Dialog_ | Identifier | Y | N
Control_ | Identifier | Y | N
Event | Formatted | Y | N
Argument | Formatted | Y | N
Condition | Condition | Y | Y
Ordering | Integer |  | Y

Columns

Dialog_
An external key to the first column of the Dialog table. Combining this field with the Control_ field identifies a unique control.
Control_
An external key to the second column of the Control table. Combining this field with the Dialog_ field identifies a unique control.
Event
An identifier that specifies the type of event that should take place when the user interacts with the control specified by Dialog_ and Control_. For a list of possible values see ControlEvent Overview.

To set a property with a control, put [Property_Name] in this field and the new value in the argument field. Put { } into the argument field to enter the NULL value.

Argument
A value used as a modifier when triggering a particular event.

For example, the argument of the NewDialog ControlEvent or the SpawnDialog ControlEvent is the name of the dialog box and the argument of the Install action is a number defining the install level.

Condition
A conditional statement that determines whether the installer activates the event in the Event column. The installer triggers the event if the conditional statement in the Condition field evaluates to True. Therefore put a 1 in this column to ensure that the installer triggers the event. The installer does not trigger the event if the Condition field contains a statement that evaluates to False. The installer does not trigger an event with a blank in the Condition field unless no other events of the control evaluate to True. If none of the Condition fields for the control named in the Control_ field evaluate to True, the installer triggers the one event having a blank Condition field, and if more than one Condition field is blank it triggers the one event of these with the largest value in the Ordering field. See Conditional Statement Syntax.
Ordering
An integer used to order several events tied to the same control. This must be a non-negative number. This field may be left blank.


CreateFolder Table

The CreateFolder table contains references to folders that need to be created explicitly for a particular component.

The CreateFolder table has the following columns.

Column | Type | Key | Nullable
Directory_ | Identifier | Y | N
Component_ | Identifier | Y | N

Columns

Directory_
External key into the first column of the Directory table.
Component_
External key into the first column of the Component table.

Remarks

The folders in this table are created when the component is installed. An attempt is made to remove these folders only when the component is uninstalled or moved to run-from-source. No automatic removal is triggered if the folders become empty. In contrast, folders created by the installer but not listed in this table are removed when they become empty.

Because folders created by the installer are deleted when they become empty, you must author an entry into the CreateFolder table to install a component that consists of an empty folder.

This table is referred to when the CreateFolders action or the RemoveFolders action is called.

For information on how to secure a folder see the LockPermissions Table.


CustomAction Table

The CustomAction table provides the means of integrating custom code and data into the installation. The source of the code that is executed can be a stream contained within the database, a recently installed file, or an existing executable file.

The CustomAction table has the following columns.

Column | Type | Key | Nullable
Action | Identifier | Y | N
Type | Integer |  | N
Source | CustomSource |  | Y
Target | Formatted |  | Y

Columns

Action
Name of the action. The action normally appears in a sequence table unless it is called by another custom action. If the name matches any built-in action, then the custom action is never called.

Primary table key.

Type
A field of flag bits specifying the basic type of custom action and options. See Summary List of All Custom Action Types for a list of the basic types. See Custom Action Return Processing Options, Custom Action Execution Scheduling Options, and Custom Action In-Script Execution Options.
Source
A property name or external key into another table. For a discussion of the possible custom action sources, see Custom Action Sources and the Summary List of All Custom Action Types. For example, the Source column may contain an external key into the first column of one of the following tables containing the source of the custom action code.

Directory table for calling existing executables.

File table for calling executables and DLLs that have just been installed.

Binary table for calling executables, DLLs, and data stored in the database.

Property table for calling executables whose paths are held by a property.

Target
An execution parameter that depends on the basic type of custom action. See the Summary List of All Custom Action Types for a description of what should be entered in this field for each type of custom action. For example, this field may contain the following depending on the custom action.
Target | Custom action
Entry point (required) | Calling a DLL.
Executable name with arguments (required) | Calling an existing executable.
Command line arguments (optional) | Calling an executable just installed.
Target file name (required) | Creating a file from custom data.
NULL | Executing script code.

See also all the topics under Custom Actions.


Dialog Table

The Dialog table contains all the dialogs that appear in the user interface in both the full and reduced modes.

The Dialog table has the following columns.

Column | Type | Key | Nullable
Dialog | Identifier | Y | N
HCentering | Integer |  | N
VCentering | Integer |  | N
Width | Integer |  | N
Height | Integer |  | N
Attributes | DoubleInteger |  | Y
Title | Formatted |  | Y
Control_First | Identifier |  | N
Control_Default | Identifier |  | Y
Control_Cancel | Identifier |  | Y

Columns

Dialog
Primary key and name of the dialog box.
HCentering
Horizontal position of the dialog box. The range is 0 to 100, with 0 at the left edge of the screen and 100 at the right edge.
VCentering
Vertical position of the dialog box. The range is 0 to 100, with 0 at the top edge of the screen and 100 at the bottom edge.
Width
Width of the rectangular boundary of the dialog box. This number must be non-negative.
Height
Height of the rectangular boundary of the dialog box. This number must be non-negative.
Attributes
A 32-bit word that specifies the attribute flags to be applied to this dialog box. This number must be non-negative. See the Dialog Style Bits list for a list of options.
Title
A localizable text string specifying the title to be displayed in the title bar of the dialog box.
Control_First
An external key to the second column of the Control table. Combining this field with the Dialog field identifies a unique control in the Control table. This defines the control that takes the focus when the dialog box is created. This column is ignored in an Error dialog box.

Because static text can not take the focus, a Text control that describes an Edit, PathEdit, ListView, ComboBox or VolumeSelectCombo control must be made the first control in the dialog box to ensure compatibility with screen readers.

Control_Default
This column is an external key to the second column of the Control table. Combining this field with the Dialog field results in a primary key into the Control table that defines the default control. Hitting the Return key is equivalent to clicking on the default control. If this column is left blank, then there is no default control. This column is ignored in the Error dialog box.
Control_Cancel
An external key to the second column of the Control table. Combining this field with the Dialog field results in a primary key of the Control table that defines the cancel control. Hitting the ESC key or clicking the Close button in the dialog box is equivalent to clicking on the cancel control. This column is ignored in an Error dialog box.

The cancel control is hidden during rollback or the removal of backed up files. The internal UI handler hides the control upon receiving a INSTALLMESSAGE_COMMONDATA message.

Remarks

The integer values for width and height are in the installer units, not dialog units. An installer unit is equal to one-twelfth the height of the 10-point MS Sans Serif font size.

The two centering values are ignored for subsequent dialog boxes in a wizard sequence. Dialog box positions are set by the user or as for the previous dialog box. These dialog box sequences are created by a NewDialog ControlEvent.


Directory Table

The Directory table specifies the directory layout for the product. Each row of the table indicates a directory both at the source and the target.

The Directory table has the following columns.

Column | Type | Key | Nullable
Directory | Identifier | Y | N
Directory_Parent | Identifier |  | Y
DefaultDir | DefaultDir |  | N

Columns

Directory
The Directory column contains a unique identifier for a directory or directory path. This column can contain the name of a property that is set to the full path of a target directory. If this column contains a property, the target directory takes the name specified in the DefaultDir column and takes the parent directory specified in the Directory_Parent column.

If the Directory_Parent column is either null or equal to the value of the Directory column, the Directory column represents a root target directory. Only one root directory may be specified in the Directory table.

Directory_Parent
This column is a reference to the directory's parent directory. A record that has a Directory_Parent column equal to NULL or equal to the Directory column represents a root directory. The full path of the parent directory is resolved by reference in the Directory_Parent column is an external key into the Directory column. For example, if a folder has a parent directory named PDIR, the parent directory of PDIR is given in the Directory_Parent column of the row with PDIR in the Directory column.
DefaultDir
The DefaultDir column contains the directory's name (localizable)under the parent directory. By default, this is the name of both the target and source directories. To specify different source and target directory names, separate the target and source names with a colon as follows: [targetname]:[sourcename].

If the value of the Directory_Parent column is NULL or is equal to the Directory column, the DefaultDir column specifies the name of a root source directory.

For a non-root source directory, a period (.) entered in the DefaultDir column indicates the directory should be located in its parent directory without a subdirectory.

The directory names in this column may be formatted as short filename | long filename pairs.

Remarks

Each record in the table represents a directory in both the source and the destination images. The Directory table must specify a single root directory with a Directory column value equal to the TARGETDIR property.

For an administrative installation, install the administrative image into the root directory named TARGETDIR and use the source directory names to resolve the target directories.

Note the installer sets a number of standard properties to system folder paths. See the Property Reference for a list of the properties that are set to system folders.

Directory resolution is performed during the CostFinalize action and is done as follows:

Root Destination Directory

There may only be a single root destination directory. To specify the root destination directory, set the Directory column to the TARGETDIR property and the DefaultDir column to the SourceDir property. If the TARGETDIR property is defined, the destination directory is resolved to the property's value. If the TARGETDIR property is undefined, the ROOTDRIVE property is used to resolve the path.

Root Source Directory

The value of the DefaultDir column for the root directory entry must be set to the SourceDir property.

Non-root Destination Directories

The Directory value for a non-root directory is also interpreted as the name of a property defining the location of the destination. If the property is defined, the destination directory is resolved to the property's value. If the property is not defined, the destination directory is resolved to a subdirectory beneath the resolved destination directory for the Directory_Parent entry. The DefaultDir value defines the name of the subdirectory.

Non-root Source Directories

The source directory for a non-root directory is resolved to a subdirectory of the resolved source directory for the Directory_Parent entry. Again, the DefaultDir value defines the name of the subdirectory.

Short or Long File Names

When resolving destination directories, the short file names specified in the DefaultDir column are used if either the SHORTFILENAMES property is set or the volume the directory is located on does not support long file names. Otherwise, the long file name is used.

Note that when the directories are resolved during the CostFinalize action, the keys in the Directory table become properties set to directory paths.

CreateFolder Table

For creating empty folders during an installation, see CreateFolder Table.

Using the Directory Table

For more information about the Directory table, including samples, see Using the Directory Table.


DrLocator Table

The DrLocator table holds the information needed to find a file or directory by searching the directory tree.

The DrLocator table has the following columns.

Column | Type | Key | Nullable
Signature_ | Identifier | Y | N
Parent | Identifier | Y | Y
Path | AnyPath | Y | Y
Depth | Integer |  | Y

Columns

Signature_
The Signature_ column is an external key to the first column of the Signature table. This field may represent a unique file signature listed in the Signature table. If the value in this column is absent from the Signature table, then the search is assumed to be for a directory pointed to by the DrLocator table.
Parent
This column is the signature of the parent directory of the file or directory in the Signature_ column. If this field is null, and the Path column does not expand to a full path, then all the fixed drives of the user's system are searched by using the Path.

This field is a key into one of the following tables: the RegLocator, the IniLocator, the CompLocator, or the DrLocator tables.

Path
The Path column contains the path on the user's system. This is a either a full path or a relative subpath below the directory specified in the Parent column. See the restrictions on the AnyPath data type.
Depth
The depth below the path that the installer searches for the file or directory specified in the Signature_ column. The value used in the Depth field is based on zero. For example, if the Path field is c:/Program Files/bin, the Depth column must be set to 0 or greater, to detect a file located inside the folder bin. If the Depth field is empty, the depth is assumed to be zero.

Remarks

This table is used with the AppSearch Table.

This table's columns are generally not localized. If an author decides to search for products in multiple languages, then there must be a separate entry included in the table for each language.

See Searching for Existing Applications, Files, Registry Entries or .ini File Entries.


DuplicateFile Table

The DuplicateFile table contains a list of files that are to be duplicated, either to a different directory than the original file or to the same directory but with a different name. The original file must be a file installed by the InstallFiles action.

The DuplicateFile table has the following columns.

Column | Type | Key | Nullable
FileKey | Identifier | Y | N
Component_ | Identifier |  | N
File_ | Identifier |  | N
DestName | Filename |  | Y
DestFolder | Identifier |  | Y

Columns

FileKey
A primary key, a non-localized token, identifying a unique DuplicateFile record.
Component_
An external key to the first column of the Component table. If the component identified by the key is not selected for installation or removal, then no action is taken on this DuplicateFile record.
File_
Foreign key into the File table representing the original file that is to be duplicated.
DestName
Localizable name to be given to the duplicate file. If this field is blank, then the destination file is given the same name as the original file.
DestFolder
Name of a property that is the full path to where the duplicate file is to be copied. If this directory is the same as the directory containing the original file and the name for the proposed duplicate file is the same as the original, then no action takes place.

Remarks

The table is processed by the DuplicateFiles action and the RemoveDuplicateFiles action.


Environment Table

The Environment table is used to set the values of environment variables.

The Environment table has the following columns.

Column | Type | Key | Nullable
Environment | Identifier | Y | N
Name | Text |  | N
Value | Formatted |  | Y
Component_ | Identifier |  | N

Columns

Environment
This is the primary key of the table and is a non-localized token.
Name
This column is the localizable name of the environment variable. The key values are written or removed depending upon which of the characters in the following table are prefixed to the name. There is no effect in the ordering of the symbols used in a prefix.
Prefix Description
= Create the environment variable if it does not exist, and then set it during installation. If the environment variable exists, set it during the installation.
+ Create the environment variable if it does not exist, then set it during installation. This has no effect on the value of the environment variable if it already exists.
- Remove the environment variable when the component is removed. This symbol can be combined with any prefix.
! Remove the environment variable during an installation.
* This prefix is used with Microsoft® Windows® NT/Windows® 2000 to indicate that the name refers to a system environment variable. If no asterisk is present, the installer writes the variable to the user's environment. Microsoft Windows 95/98 ignores the asterisk and add the environment variable to autoexec.bat. This symbol can be combined with any prefix.
=- The environment variable is set on install and removed on uninstall. This is the usual behavior.
!- Removes an environment variable during an install or uninstall.
=+

!+

!=

 These are not a valid prefixes

If the Value field in the table includes a [~], then the prefix characters apply to only the specified portion of the string. The use of [~] is described below in the Value column section.

The environment variable is removed if the Value field of the table is blank. Therefore, with a blank in the Value field, an = prefix deletes the environment variable on install and a - prefix deletes any current values on uninstall.

Value
This column contains the localizable value that is to be set as a formatted string. See Formatted. If this field is left blank, the variable is removed. If the field is blank and the string in the Name field is prefixed by the - symbol, the variable is removed only when the component is removed.

To append a value to the end of an existing variable, prefix the string in this field by the Null character [~] and the separator character. For example, if the semicolon is the chosen separator: [~];Value.

To prefix a value to the front of an existing variable, append the string in this field by the separator character and the Null character [~]. For example, if the semicolon is the chosen separator: Value;[~] .

If no [~] is present in the field, the string represents the entire value to be set or deleted.

Component_
An external key to the first column of the Component table. This column references the component that controls the installation of the environment values.

Remarks

For the installer to set environment variables, the WriteEnvironmentStrings action and RemoveEnvironmentStrings action need to be listed in the InstallExecuteSequence Table.

Note that environment variables do not change for the installation in progress when either the WriteEnvironmentStrings action or RemoveEnvironmentStrings action are run. On Windows NT and Windows 2000, this information is stored in the registry and a message notifies the system of changes when the installation completes. A new process, or another process that checks for these messages, uses the new environment variables. On Windows 95 and Windows 98, this information is stored in the Autoexec.bat file, and do not affect the system until a system reboot.

When modifying the path environment variable with the Environment table, do not attempt to enter the entire new path explicitly into the Value field. Instead, extend the existing path by prefixing or appending a value and delimiter (;) to [~]. If [~] is not present in the Value field, the existing path information is lost and installing the .msi file may prevent the computer from booting. The path variable is mostly commonly set using the syntax: [~];Value.


Error Table

The Error table is used to look up error message formatting templates when processing errors with an error code set but without a formatting template set (this is the normal situation).

The Error table has the following columns.

Column | Type | Key | Nullable
Error | Integer | Y | N
Message | Template |  | Y

Columns

Error
See Windows Installer Error Messages for a list of the error numbers and messages.

The error number must be a non-negative integer.

The range from 25000 to 30000 is reserved for errors from custom actions. Authors of custom action may use this range for their custom actions.

Message
This column contains the localizable error formatting template. The Error table is generated by the initial build process to contain the debug format templates.

The following table lists reserved messages. For a list of ship and internal error codes see Windows Installer Error Messages.
Code | Message | Remarks
0 | {{Fatal error: }}
1 | Error [1].
2 | Warning [1].
3
4 | Info [1].
5 | Internal Error [1]. [2]{, [3]}{, [4]}
6
7 | {{Disk full: }}
8 | Action [Time]: [1]. [2]
9 | [ProductName]
10 | {[2]}{, [3]}{, [4]}
11 | Message type: [1], Argument: [2]
12 | === Logging started: [Date] [Time] ===
13 | === Logging stopped: [Date] [Time] ===
14 | Action start [Time]: [1]
15 | Action ended [Time]: [1]. Return value [2]
16 | Time remaining: {[1] min }{[2] sec}
17 | Out of memory. Shutdown other applications before retrying
18 | Installer is no longer responding
19 | Installer terminated prematurely
20 | Please wait while Windows configures [ProductName]...
21 | Gathering required information...
32 | {[ProductName] }Setup completed successfully.
33 | {[ProductName] }Setup failed.

Remarks

The template does not include formatting for the error number in field 1. When processing the error, the installer attaches a header prefix to the template depending on the message type as described in the previous table. These headers are also stored in the Error table.


EventMapping Table

The EventMapping table lists the controls that subscribe to some event and lists the attribute to be changed when the event is published.

The EventMapping table has the following columns.

Column | Type | Key | Nullable
Dialog_ | Identifier | Y | N
Control_ | Identifier | Y | N
Event | Identifier | Y | N
Attribute | Identifier |  | N

Columns

Dialog_
An external key to the first column of the Dialog table. Combined this field with the Control_ field identifies a control.
Control_
An external key to the second column of the Control table. Combined this field with the Dialog_ field, identifies a control.
Event
This field is identifier that specifying the type of the event subscribed to by the control. See ControlEvent Overview.
Attribute
The name of the control attribute that is set when the event in the Event column is received. The argument of the event is passed as the argument of the Attribute call to change this attribute of the control. If this column is left blank, then no attribute of the control is changed by the event. In this case, the control that published the event can still enable, disable, hide, or unhide the control.

Remarks

More than one control on a dialog box can subscribe to the same event.


Extension Table

The Extension table contains information about file name extension servers that must be generated as a part of product advertisement. Each row generates a set of registry keys and values.

The Extension table has the following columns.

Column | Type | Key | Nullable
Extension | Text | Y | N
Component_ | Identifier | Y | N
ProgId_ | Text |  | Y
MIME_ | Text |  | Y
Feature_ | Identifier |  | N

Columns

Extension
The extension associated with the table row. The extension can be up to 255 characters long. Enter the extension in this field without the preceding period.
Component_
An external key to the first column of the Component table. This column references the component that controls the installation of the environment values.
ProgId_
The Program ID associated with this extension. This is a foreign key into the ProgId table.
MIME_
The Content Type that is to be written for the Extension column.

An external key to the first column of the MIME table.

Feature_
An external key into the first column of the Feature table specifying the feature that provides the extension server.

Remarks

This table is referred to when the RegisterExtensionInfo action or the UnRegisterExtensionInfo action is executed.


Feature Table

The Feature table defines the logical tree structure of features and has the following columns.

Column | Type | Key | Nullable
Feature | Identifier | Y | N
Feature_Parent | Identifier |  | Y
Title | Text |  | Y
Description | Text |  | Y
Display | Integer |  | Y
Level | Integer |  | N
Directory_ | Identifier |  | Y
Attributes | Integer |  | N

Columns

Feature
Primary key used to identify a particular feature record.
Feature_Parent
This is an optional key of a parent record in the same table. The key points to the Feature column. If the parent feature is not selected, then this feature is not installed. A Null in this field indicates that this feature has no parent and is a root item. The Feature_Parent column must not equal the Feature column of the same record.
Title
Short string of text identifying the feature. This string is listed as an item by the SelectionTree control of the Selection Dialog.
Description
Longer string of text describing the feature. This localizable string is displayed by the Text control of the Selection Dialog.
Display
The number in this field specifies the order in which the feature is to be displayed in the user interface. The value also determines if the feature is initially displayed expanded or collapsed.

If the value is Null or zero, then the record is not displayed. If the value is odd, then the feature node is expanded initially. If the value is even, then the feature node is collapsed initially.

Level
The initial install level of this feature. Processing the Condition table can modify the Level value. For more details, see Install Level in the Remarks section that follows.

An install level of zero disables the item and prevents it from being displayed.

Directory_
The Directory_ column contains the name of a directory that can be configured by a Selection Dialog. If a property is used in this column it must be a public property. Because this column is a key into the Directory table, the directories listed in this column must also be listed in that table.
Attributes
This field specifies the remote execution option for features that have not yet been installed and for which no feature state request has been made using any of the following properties.

ADDLOCAL

ADDSOURCE

ADDDEFAULT

COMPADDLOCAL

COMPADDSOURCE

FILEADDLOCAL

FILEADDSOURCE

REMOVE

REINSTALL

ADVERTISE

Add the indicated bits to the total value of this column to include a remote execution option. If this field is left blank, the value defaults to 0, msidbFeatureAttributesFavorLocal. If the feature's install level is 0 or is greater than or equal to the current install level, no change is made in the feature's state.
Bit flag name | Decimal | Hexadecimal | Feature state
msidbFeatureAttributesFavorLocal | 0 | 0x0000 | Components of this feature that are not marked for installation from source are installed locally. A component shared by two or more features, some of which are set to msidbFeatureAttributesFavorLocal and some to msidbFeatureAttributesFavorSource, is installed locally. Components marked irsSourceOnly in the Component table are always run from the source CD/server. The bits msidbFeatureAttributesFavorLocal and msidbFeatureAttributesFavorSource work with features not listed by the ADVERTISE property.
msidbFeatureAttributesFavorSource | 1 | 0x0001 | Components of this feature not marked for local installation are installed to run from the source CD-ROM or server. A component shared by two or more features, some of which are set to msidbFeatureAttributesFavorLocal and some to msidbFeatureAttributesFavorSource, is installed to run locally. Components marked irsLocalOnly in the Component table are always installed locally. The bits msidbFeatureAttributesFavorLocal and msidbFeatureAttributesFavorSource work with features not listed by the ADVERTISE property.
msidbFeatureAttributesFollowParent 2 0x0002 Set this attribute and the state of the feature is the same as the state of the feature's parent. You cannot use this option with a feature that is a parent.

Omit this attribute and the feature state is determined according to msidbFeatureAttributesDisallowAdvertise and msidbFeatureAttributesFavorLocal and msidbFeatureAttributesFavorSource.

To guarantee that the child feature's state always follows the state of its parent, even when the child and parent are initially set to absent in the SelectionTree control, you must include both msidbFeatureAttributesFollowParent and msidbFeatureAttributesUIDisallowAbsent in the attributes of the child feature.
msidbFeatureAttributesFavorAdvertise 4 0x0004 Set this attribute and the feature state is Advertise. If the feature is listed by the ADDDEFAULT property this bit is ignored and the feature state is determined according to msidbFeatureAttributesFavorLocal and msidbFeatureAttributesFavorSource.

Omit this attribute and the feature state is determined according to msidbFeatureAttributesDisallowAdvertise and msidbFeatureAttributesFavorLocal and msidbFeatureAttributesFavorSource.
msidbFeatureAttributesDisallowAdvertise 8 0x0008 Note that this bit works only with features that are listed by the ADVERTISE property.

Set this attribute and if the listed feature is not a parent or child, the feature is installed according to msidbFeatureAttributesFavorLocal and msidbFeatureAttributesFavorSource.

Set this attribute for the parent of a listed feature and the parent is installed.

Set this attribute for the child of a listed feature and the state of the child is Absent.

Omit this attribute and if the listed feature is not a parent or child, the feature state is Advertise.

Omit this attribute and if the listed feature is a parent or child, the state of both features is Advertise.
msidbFeatureAttributesUIDisallowAbsent 16 0x0010 Set this attribute and the user interface does not display an option to change the feature state to Absent.

Omit this attribute and the user interface displays an option to change the feature state to Absent.
msidbFeatureAttributesNoUnsupportedAdvertise 32 0x0020 Set this attribute and advertising is disabled for the feature if the operating system shell does not support Windows Installer descriptors.

Omit this attribute and advertising is not disabled.

Some attributes are exclusive of each other. Attempting to set these attributes together on the same feature causes the installation package to fail package validation.

  • Do not use msidbFeatureAttributesFavorAdvertise with msidbFeatureAttributesDisallowAdvertise.
  • Do not use msidbFeatureAttributesNoUnsupportedAdvertise with msidbFeatureAttributesDisallowAdvertise together.
  • Do not use msidbFeatureAttributesFollowParent with msidbFeatureAttributesFavorSource.
  • Note that the msidbFeatureAttributesFollowParent and msidbFeatureAttributesFavorLocal values are mutually exclusive. If the msidbFeatureAttributesFollowParent value is used, the msidbFeatureAttributesFavorLocal value is assumed to not exist.

Remarks

Several additional temporary columns are added to this table when it is loaded into memory for computations used by costing and user interface selection.

A component can be shared between two or more features or applications. If two or more features refer to the same component, then that component is selected for installation if any of the associated features are selected. This can also be the reason child features are not uninstalled when a parent feature is removed. If the child feature consists of components needed by other features or applications, the installer does not remove the child feature.

Install Level

For any installation, there is a defined Install Level, which is an integral value from 1 to 32,767. The initial value is determined by the InstallLevel property, which is set in the Property table.

A feature is installed only if the feature Level value is less than or equal to the current Install Level. The user interface can be authored such that once the installation is initialized, the installer allows the user to modify the Install Level of any feature in the Feature table. For example, an author can define Install Level values that represent specific installation options, such as Complete, Typical, or Minimum, and then create a dialog box that uses SetInstallLevel ControlEvents to enable the user to select one of these states. Depending on the state the user selects, the dialog box sets the InstallLevel property to the corresponding value. If the author assigns Typical a level of 100 and the user selects Typical, only those features with a Level of 100 or less are installed. In addition, the Custom option could lead to another dialog box containing a Selection Tree control. The Selection Tree would then allow the user to individually change whether each feature is installed.


FeatureComponents Table

The FeatureComponents table defines the relationship between features and components. For each feature, this table lists all the components that make up that feature.

The FeatureComponents table has the following columns.

Column | Type | Key | Nullable
Feature_ | Identifier | Y | N
Component_ | Identifier | Y | N

Columns

Feature_
An external key into the first column of the Feature table.
Component_
An external key into the first column of the Component table.

Remarks

There is a maximum limit of 1600 components per feature using Windows NT/Windows 2000 and a maximum limit of 800 components per feature using Windows 95 and Windows 98.

Components can be shared by two or more features, that is, the same component can be referred to by more than one feature.

This table is referred to when the PublishFeatures action or the UnpublishFeatures action is executed.


File Table

The File table contains a complete list of source files with their various attributes, ordered by a unique, non-localized, identifier. Files can be stored on the source media as individual files or compressed within a cabinet file. See also Cabinet Files.

The File table has the following columns.

Column | Type | Key | Nullable
File | Identifier | Y | N
Component_ | Identifier |  | N
FileName | Filename |  | N
FileSize | DoubleInteger |  | N
Version | Version |  | Y
Language | Language |  | Y
Attributes | Integer |  | Y
Sequence | Integer |  | N

Columns

File
A non-localized token that uniquely identifies the file and is used as an external key into other tables.
Component_
External key into the first column of the Component table. This field identifies the Component that controls the file.
FileName
The file name used for installation. The name may be localized. For the file name syntax see the Filename column data type.

Because some web servers can be case sensitive, FileName should match the case of the source files exactly to insure support of internet downloads.

FileSize
Size of the file in bytes. This must be a non-negative number.
Version
This field is the version string for a versioned file. This field is blank for non-versioned files. The file version entered into this field must be identical to the version of the file included with the installation package.

The Version field can also be set to contain the primary key of another record in the File table. The referenced file then determines the versioning logic for this file. See Companion Files. Note that if this file is the key path for its component, it must not be specified as a companion file.

Language
A list of decimal language IDs separated by commas.

Font files should not be authored with a language ID, as fonts do not have an embedded language ID resource.Thus this column should be left null for font files.

Attributes
Integer containing bit flags representing file attributes.

The following table shows the definition of the bit field.
Constant | Hexadecimal | Decimal | Description
msidbFileAttributesReadOnly | 0x000001 | 1 | Read-Only
msidbFileAttributesHidden | 0x000002 | 2 | Hidden
msidbFileAttributesSystem | 0x000004 | 4 | System
msidbFileAttributesVital | 0x000200 | 512 | The file is vital for the proper operation of the component to which it belongs
msidbFileAttributesChecksum | 0x000400 | 1024 | The file contains a valid checksum. A checksum is required to repair a file that has become corrupted.
msidbFileAttributesPatchAdded | 0x001000 | 4096 | This bit must only be added by a patch and if the file is being added by the patch.
msidbFileAttributesNoncompressed | 0x002000 | 8192 | The file's source type is uncompressed. If set, ignore the Word Count Summary Property. If neither msidbFileAttributesNoncompressed or msidbFileAttributesCompressed are set, the compression state of the file is specified by the Word Count Summary Property. Do not set both msidbFileAttributesNoncompressed and msidbFileAttributesCompressed.
msidbFileAttributesCompressed | 0x004000 | 16384 | The file's source type is compressed. If set, ignore the Word Count Summary Property. If neither msidbFileAttributesNoncompressed or msidbFileAttributesCompressed are set, the compression state of the file is specified by the Word Count Summary Property. Do not set both msidbFileAttributesNoncompressed and msidbFileAttributesCompressed.

If the msidbFileAttributesVital bit within the Attributes column is set, and if the component to which the file belongs is selected for installation, then the installer must be able to install this file for the installation to be completed successfully. If the installer is unable to install the file for some reason (for example, if the source file cannot be located within the source image), then an error dialog box will appear with the options "Retry" or "Cancel". For a file that does not have msidbFileAttributesVital set, the options in case of an install error will be "Abort", "Retry", and "Ignore" (that is, the user will have the option to complete the install successfully without installing that file).

The msidbFileAttributesChecksum bit within the Attributes column should be set for every executable file in the installation that has a valid checksum stored in the Portable Executable (PE) file header. Only those files that have this bit set will ever be verified for valid checksum during a reinstall (see the REINSTALLMODE property for more information).

Sequence
Sequence position of this file on the media images. This order must correspond to the order of the files in the cabinet if the files are compressed. The integers in this field must be equal or greater than 1.

The sequence numbers in the Sequence column are used to specify both the order of installation for files and the source media upon which the file is located (in conjunction with the Media table). For example, suppose a file has a sequence number of 92. To determine the source disk this file resides on, look in the Media table for the entry with the smallest Last Sequence value that is larger than 92.

Although compressed files are assigned internal sequence numbers within cabinets, those absolute numbers do not need to match the sequence numbers within the File table. It is, however, important that the sequence of files in the File table be identical to the sequence of the files within the cabinets.

For files that aren't compressed, the sequence numbers need not be unique. For instance, if all your files are uncompressed, and all reside on one disk, you could give all the files the same sequence number.

Remarks

The table is initially generated from the file list, but if cabinet compression is used, the table is regenerated from the output of the compression engine. See also Cabinet Files.

To move an existing file on the user's computer during the installation use the MoveFiles action and MoveFile table. To install a file to multiple locations use the DuplicateFiles action and the DuplicateFile table.

The following table summarizes the possible combinations of values in the Version column and the Language column. For more information, see File Versioning Rules.

Version | Language | Description
1.2.3.4 | 1033 | version and language
1.2.3.4 | (Null) | version but no language (Not valid with Windows Installer version 1.0)
1.2.3.4 | 0 | version and language are neutral
Testdb | (Null) | companion file with no language associated with it
Testdb | 1033 | companion file and language
(Null) | 1033 | no version, but has a language associated with it (that is, typelib, helpfile).

For information on how to secure a file see the LockPermissions Table.


FileSFPCatalog Table

The FileSFPCatalog table associates specified files with the catalog files used by Windows Millennium Edition for Windows File Protection.

The FileSFPCatalog table has the following columns.

Column | Type | Key | Nullable
File_ | Identifier | Y | N
SFPCatalog_ | Filename | Y | N

Columns

File_
Foreign key to the File table.
SFPCatalog_
Foreign key to the SFPCatalog table.

Remarks

This feature is not available in Windows Installer versions 1.0 or 1.1.

Windows File Protection for Windows Millennium Edition is provided with Windows Installer version 1.2. For more information see Windows File Protection on Windows Millennium Edition.

The InstallSFPCatalogFile action queries the Component table, File table, FileSFPCatalog table and SFPCatalog table.


Font Table

The Font table contains the information for registering font files with the system.

The Font table has the following columns.

Column | Type | Key | Nullable
File_ | Identifier | Y | N
FontTitle | Text |  | Y

Columns

File_
External key into the File table entry for the font file. It is recommended that the component containing the font file have the FontsFolder specified in the Directory_ column of the Component table.
FontTitle
Font name. It is recommended that you leave this column null for TrueType Fonts and TrueType Collections because the installer can register the font after reading the correct font title from the font file. If the font name is entered, it must be identical to font title from the font file. You must specify a title for fonts that do not have embedded names, such as .fon files.

Remarks

This table is referred to when the RegisterFonts action or the UnregisterFonts action is executed.

If the FontTitle field is left Null, the Font name is read directly from the font file specified. If the font name recorded into the FontTitle field differs from the internal font name recorded in the font file, the font is registered twice by the RegisterFonts action.

Font files should not be authored with a language ID, as fonts do not have an embedded language ID resource.Thus the Language column of the File table should be left null for font files.

Because the installer does not refcount font files by default, preexisting font files may be removed with their component when uninstalling an application. To ensure that a font file is not removed, authors may set the msidbComponentAttributesSharedDllRefCount or msidbComponentAttributesPermanent bit flags in the Attributes column of the Component Table_msi_Component_Table for the component containing the font file.


Icon Table

This table contains the icon files. Each icon from the table is copied to a file as a part of product advertisement to be used for advertised shortcuts and OLE servers. See OLE Limitations on Streams.

The Icon table has the following columns.

Column | Type | Key | Nullable
Name | Identifier | Y | N
Data | Binary |  | N

Columns

Name
Name of the icon file.
Data
The binary icon data in PE (.dll or .exe) or icon (.ico) format.

Remarks

This table is referred to when the PublishProduct action is executed.

The icons for shortcuts, file extensions, and CLSIDs must be stored in files that are separate from the target file itself. This is required because the installer should copy only the small icon files to the user's machine when advertising the resource. A developer of an installation package therefore needs to author separate files containing only the icons. These icon files are then stored as binary data in the Icon table.

Icon files that are associated strictly with file extensions or CLSIDs can have any extension, such as .ico. However, Icon files that are associated with shortcuts must be in the EXE binary format and must be named such that their extension matches the extension of the target. The shortcut will not work if this rule is not followed. For example, if a shortcut is to point to a resource having the key file Red.bar, then the icon file must also have the extension .bar. Multiple icons can be stuffed into the same icon file as long as all of the target files have the same extension.


IniFile Table

The IniFile table contains the .ini information that the application needs to set in an .ini file.

The IniFile table has the following columns.

Column | Type | Key | Nullable
IniFile | Identifier | Y | N
FileName | Text |  | N
DirProperty | Identifier |  | Y
Section | Formatted |  | N
Key | Formatted |  | N
Value | Formatted |  | N
Action | Integer |  | N
Component_ | Identifier |  | N

Columns

IniFile
The key for this table.
FileName
The localizable name of the .ini file in which to write the information.
DirProperty
Name of a property having a value that resolves to the full path of the the folder containing the .ini file. The property can be the name of a directory in the Directory table, a property set by the AppSearch table, or any other property that represents a full path. If this field is left blank, the .ini file is created in the folder having the full path specified by the WindowsFolder property.
Section
The localizable .ini file section.
Key
The localizable .ini file key within the section.
Value
The localizable value to be written.
Action
The type of modification to be made.
Constant | Hexadecimal | Decimal | Modification
msidbIniFileActionAddLine | 0x000 | 0 | Creates or updates a .ini entry.
msidbIniFileActionCreateLine | 0x001 | 1 | Creates a .ini entry only if the entry does not already exist.
msidbIniFileActionAddTag | 0x003 | 3 | Creates a new entry or appends a new comma-separated value to an existing entry.

Component_
External key into the first column of the Component table referencing the component that controls the installation of the .ini value.

Remarks

The .ini file information is written out when the corresponding component has been selected to be installed as local or run from source.

This table is referred to when the WriteIniValues action or the RemoveIniValues action is executed.


IniLocator Table

The IniLocator table holds the information needed to search for a file or directory using an .ini file or to search for a particular .ini entry itself. The .ini file must be present in the default Microsoft Windows directory.

The IniLocator table has the following columns.

Column | Type | Key | Nullable
Signature_ | Identifier | Y | N
FileName | Text |  | N
Section | Text |  | N
Key | Text |  | N
Field | Integer |  | Y
Type | Integer |  | Y

Columns

Signature_
An external key into the first column of the Signature table. The Signature_ represents a unique signature and is also the external key into column one of the Signature table. If this signature is present in the Signature table, then the search is for a file. If this key is absent from the Signature table, and the value of the Type column is msidbLocatorTypeRawValue, the search is for the .ini entry specified by the IniLocator table. Otherwise the search is for a directory specified by the IniLocator table.
FileName
The .ini file name.
Section
Section name within the .ini file.
Key
Key value within the section.
Field
The field in the .ini line. If Field is Null or 0, then the entire line is read. This must be a non-negative number.
Type
A value that determines whether the .ini value is a file name, a directory location, or raw .ini value.

The following table lists valid values. If absent, Type is set to be 1.
Constant | Hexadecimal | Decimal | Description
msidbLocatorTypeDirectory | 0x000 | 0 | Key path is a directory.
msidbLocatorTypeFileName | 0x001 | 1 | Key path is a file name.
msidbLocatorTypeRawValue | 0x002 | 2 | Key path is a registry value.

Remarks

This table is used with the AppSearch Table.

This table's columns are generally not localized. If an author decides to search for products in multiple languages, then there can be a separate entry included in the table for each language.

Associated localized text for progress display or logging is specified in the ActionText table.

See Searching for Existing Applications, Files, Registry Entries or .ini File Entries.


InstallExecuteSequence Table

The InstallExecuteSequence table lists actions that are executed when the top-level INSTALL action is executed.

Actions in the install sequence up to the InstallValidate action, and any exit dialog boxes, are located in the InstallUISequence table. All actions from the InstallValidate through the end of the install sequence are in the InstallExecuteSequence table. Because the InstallExecuteSequence table needs to stand alone, it has any necessary initialization actions such as the LaunchConditions, CostInitialize, FileCost, and CostFinalize actions.

Custom actions requiring a user interface should use MsiProcessMessage instead of authored dialog boxes created using the Dialog table.

The InstallExecuteSequence table has the following columns.

Column | Type | Key | Nullable
Action | Identifier | Y | N
Condition | Condition |  | Y
Sequence | Integer |  | N

Columns

Action
Name of the action to execute. This is either a built-in action or a custom action.

Primary table key.

Condition
This field contains a conditional expression. If the expression evaluates to False, then the action is skipped. If the expression syntax is invalid, then the sequence terminates, returning iesBadActionData. For information on the syntax of conditional statements, see Conditional Statement Syntax.
Sequence
Number that determines the sequence position in which this action is to be executed.

A positive value represents the sequence position. A Null value indicates that the action is not executed. The following negative values indicate that this action is to be executed if the installer returns the associated code.
Termination flag | Value | Description
msiDoActionStatusSuccess | -1 | Successful completion.
msiDoActionStatusUserExit | -2 | User terminates install.
msiDoActionStatusFailure | -3 | Fatal exit terminates.
msiDoActionStatusSuspend | -4 | Install is suspended.

Zero, all other negative numbers, or a Null value indicate that the action is never run.

Remarks

Localized text for progress display or logging is specified in the ActionText table.

For an example of a sequence table, see Using a Sequence Table.


InstallUISequence Table

The InstallUISequence table lists actions that are executed when the top-level INSTALL action is executed and the internal user interface level is set to full UI or reduced UI. The installer skips the actions in this table if the user interface level is set to basic UI or no UI. See About the User Interface.

Actions in the install sequence up to the InstallValidate action, and the exit dialog boxes, are located in the InstallUISequence table. All actions from the InstallValidate through the end of the install sequence are in the InstallExecuteSequence table. Because the InstallExecuteSequence table needs to stand alone, it has any necessary initialization actions such as the LaunchConditions, CostInitialize, FileCost, and the CostFinalize, and ExecuteAction action.

The InstallUISequence table has the following columns.

Column | Type | Key | Nullable
Action | Identifier | Y | N
Condition | Condition |  | Y
Sequence | Integer |  | N

Columns

Action
Name of the action to execute. This is either a built-in action, a custom action, or a user interface wizard.

Primary table key.

Condition
This field contains a conditional expression. If the expression evaluates to False, then the action is skipped. If the expression syntax is invalid, then the sequence terminates, returning iesBadActionData. For information on the syntax of conditional statements, see Conditional Statement Syntax.
Sequence
The number in this column determines the sequence position in which this action is run.

A positive value represents the sequence position. A Null value indicates that the action is never run. The following negative values indicate that this action is executed if the installer returns the associated code.
Termination flag | Value | Description
msiDoActionStatusSuccess | -1 | Successful completion.
msiDoActionStatusUserExit | -2 | User terminates install.
msiDoActionStatusFailure | -3 | Fatal exit terminates.
msiDoActionStatusSuspend | -4 | Install is suspended.

Zero, all other negative numbers, or a Null value indicate that the action is never run.

Remarks

Associated localized text for progress display or logging is specified in the ActionText table.

For an example of a sequence table, see Using a Sequence Table.


IsolatedComponent Table

Each record of the IsolatedComponent table associates the component specified in the Component_Application column (commonly an .exe) with the component specified in the Component_Shared column (commonly a shared DLL). The IsolateComponents action installs a copy of Component_Shared into a private location for use by Component_Application. This isolates the Component_Application from other copies of Component_Shared that may be installed to a shared location on the computer. See Isolated Components.

To link one Component_Shared to multiple Component_Application, include a separate record for each pair in the IsolatedComponents table. The installer copies the files of Component_Shared into the directory of each Component_Application that is installed.

The IsolatedComponent table has the following columns.

Column | Type | Key | Nullable
Component_Shared | Identifier | Y | N
Component_Application | Identifier | Y | N

Columns

Component_Shared
Foreign key into the Component table. The component that contains the shared file, usually a DLL. The DLL should be the key file for this component. This must be a different component than listed in the Component_Application column.

The shared component controls the registration for all the isolated copies of the component and must have the msidbComponentAttributesShared DllRefCount bit flag set in the Attributes column of the Component table. This ensures that the installer can manage the life of the shared component.

Component_Application
Foreign key into the Component table. The component that contains the .exe which loads the shared file. The .exe should be the key file for this component. This must be a different component than listed in the Component_Shared column.

Remarks

The IsolatedComponent table is available with Windows Installer version 1.1. Earlier versions of the installer ignore the IsolatedComponent table and always share components.


LaunchCondition Table

The LaunchCondition table is used by the LaunchConditions action. It contains a list of conditions that all must be satisfied for the installation to begin.

The LaunchCondition table has the following columns.

Column | Type | Key | Nullable
Condition | Condition | Y | N
Description | Formatted |  | N

Columns

Condition
Expression that must evaluate to True for installation to begin.
Description
Localizable text to display when the condition fails and the installation must be terminated.


ListBox Table

The lines of a list box are not treated as individual controls, but they are part of a list box that functions as a control. The ListBox table defines the values for all list boxes.

The ListBox table has the following columns.

Column | Type | Key | Nullable
Property | Identifier | Y | N
Order | Integer | Y | N
Value | Formatted |  | N
Text | Formatted |  | Y

Columns

Property
A named property to be tied to this item. All the items tied to the same property become part of the same list box.
Order
A positive integer used to determine the ordering of the items that appear in a single list box. If the list box is defined as ordered, then all items should have an Order value. The integers do not have to be consecutive. If the list box is defined as unordered, then this column is ignored.
Value
The value string associated with this item. Selecting the line sets the associated property to this value.
Text
The localizable, visible text to be assigned to the item. If this entry or the entire column is missing, the text defaults to the corresponding entry in Value.

Remarks

The contents of the Value and Text fields are formatted by the MsiFormatRecord function when the control is created, therefore they can contain any expression that the MsiFormatRecord function can interpret. The formatting occurs only when the control is created, and it is not updated if a property involved in the expression is modified during the life of the control.


ListView Table

The lines of a listview are not treated as individual controls, but they are part of a listview that functions as a control. The ListView table defines the values for all listviews.

The ListView table has the following columns.

Column | Type | Key | Nullable
Property | Identifier | Y | N
Order | Integer | Y | N
Value | Formatted |  | N
Text | Formatted |  | Y
Binary_ | Identifier |  | Y

Columns

Property
A named property to be tied to this item. All the items tied to the same property become part of the same listview.
Order
A positive integer used to determine the ordering of the items that appear in a single listview list. The integers do not have to be consecutive. If a listview is defined as ordered, then all the items should have an Ordering value. If the listview is defined as unordered, then this column is ignored.
Value
The value string associated with this item. Selecting the line sets the associated property to this value.
Text
The visible, localizable text to be assigned to the item. If this entry or the entire column is missing, then the text defaults to the corresponding entry in Value.
Binary_
The image data for the icon. This is a foreign key to the Binary table.

Remarks

The contents of the Value and Text fields are formatted by the MsiFormatRecord function when the control is created, therefore they can contain any expression that the MsiFormatRecord function can interpret. The formatting occurs only when the control is created, and it is not updated if a property involved in the expression is modified during the life of the control.


LockPermissions Table

The LockPermissions table is used to secure individual portions of your application in a locked-down environment. It can be used with the installation of files, registry keys, and created folders.

The LockPermissions table has the following columns.

Column | Type | Key | Nullable
LockObject | Identifier | Y | N
Table | Text | Y | N
Domain | Formatted | Y | Y
User | Formatted | Y | N
Permission | DoubleInteger |  | Y

Columns

LockObject
This column and the Table column together specify the file, directory, or registry key that is to be secured. The LockObject column is a foreign key pointing into the primary key of the table specified by the Table column.
Table
This column and the LockObject column specify the file, directory, or registry key that is to be secured. In the Table column, enter either File, Registry, or CreateFolder to specify a LockObject listed in the File table, Registry table, or the CreateFolder table.
Domain
Specifies the domain of the user for which permissions are to be set. This is the name of a stand-alone machine or a domain name. The column data type is Formatted, and with Windows Installer version 1.5 or later you may get the current domain by using the string %USERDOMAIN to get the value of the USERDOMAIN environment variable. To get any other domain requires using a custom action.
User
Specifies the localized name of the user for which permissions are to be set. This name must be located on the machine or domain. The installation fails if the machine or domain controller does not recognize the domain and user combination or if the user's security identifier (SID) cannot be retrieved. Multiple users can be specified for a single LockObject.

With Windows Installer version 1.5 or later, the common user names "Everyone," and "Administrators" may be entered in English and are mapped to Well-Known SIDs. LocalSystem is given full control in all security descriptors created through the LockPermissions table. You may use the ComputerName property, LogonUser property, or the USERNAME property in this field to get the current user. A custom action is required to enter the localized name of any other user or group.

Note that you can use multiple records with identical LockObject and Table entries (but different User entries) to specify access control lists for multiple users.

Permission
An integer description of system privileges. The following gives the most commonly used values and a complete list exists in WINNT.H.
Privilege constant | Hexadecimal | Decimal
GENERIC_ALL | 0X10000000 | 268435456
GENERIC_EXECUTE | 0X20000000 | 536870912
GENERIC_WRITE | 0X40000000 | 1073741824

Note that you cannot specify GENERIC_READ in the Permission column. Attempting to do so will fail. Instead, you must specify a value such as KEY_READ or FILE_GENERIC_READ.

Null entered in this column is reserved for future use.

Remarks

It is recommended that the system administrator's local group be included in all access control lists. This ensures that the system administrator is able to access and maintain objects.

Every file, registry key, or directory that is listed in the LockPermissions table receives an explicit security descriptor, whether it replaces an existing object. The installer attempts to preserve the security on objects that already exist on the system. If an object is not listed in the LockPermissions table, and replaces an existing object, the replacement gets the security settings of the object it replaces. If an object is not listed in the LockPermissions table, and replaces an object with no explicit security descriptor, the replacement receives no explicit security descriptor.

If an object is not listed in the LockPermissions table, and does not replace an existing object, it receives no explicit security descriptor. If an object is not listed in the LockPermissions table, and does not replace an existing object, the access to the new object is based on the attributes of its parent or container object. If an object is not listed in the table, and replaces an object with no explicit security descriptor, the access to the new object is based on the attributes of its parent or container object. The security settings of child registry keys are determined by the parent registry key and the security settings of files are determined by their directory. In general, it is not recommended to secure individual files and registry keys. Instead secure the directories or top level registry keys for your product or user. Access to a file is then automatically determined by the directory that contains it and access to a registry key is determined by the parent key.


Media Table

The Media table describes the set of disks that make up the source media for the installation.

The Media table has the following columns.

Column | Type | Key | Nullable
DiskId | Integer | Y | N
LastSequence | Integer |  | N
DiskPrompt | Text |  | Y
Cabinet | Cabinet |  | Y
VolumeLabel | Text |  | Y
Source | Property |  | Y

Columns

DiskId
Determines the sort order for the table. This number must be equal or greater than 1.
LastSequence
File sequence number for the last file for this media. The numbers in the LastSequence column specify which of the files in the File table are found on a particular source disk. Each source disk contains all the files whose sequence numbers (as shown in the Sequence column of the File table) are less than or equal to the value in the LastSequence column, and greater than the LastSequence value of the previous disk (or greater than 0, for the first entry in the Media table). This number must be non-negative.
DiskPrompt
The disk name, which is usually the visible text printed on the disk. This localizable text is used to prompt the user when this disk needs to be inserted.
Cabinet
The name of the cabinet if some or all of the files stored on the media are compressed into a cabinet file. If no cabinets are used this column must be blank. The name of the cabinet must use the syntax of the Cabinet data type. Note that to conserve disk space, the installer always removes any cabinets embedded in the .msi file before caching the installation package on the user's computer.
VolumeLabel
The label attributed to the volume. This is the volume label returned by the GetVolumeInformation function. If the SourceDir property refers to a removable (floppy or CD-ROM) volume, then this volume label is used to verify that the proper disk is in the drive before attempting to install files. The entry in this column must match the volume label of the physical media.
Source
This field is only used by patching and is otherwise left blank. A patch transform can enter a property here that is the location of the cabinet file containing the patch files or any new files added by the patch. A different source needs to be specified for these files because the source of the patch package can be stored separately from the product's source. If the Cabinet field is empty, the installer ignores the value in this column. If this field is empty, the installer uses the value of the SourceDir property as the source of the cabinet.

Remarks

If the cabinet name is preceded by a number sign (#), then the files referencing this Media table record are packed in a cabinet file that is stored within the database as a separate stream.

Determining the SourceMode

The Word Count Summary Property determines the source mode for the current install. If this property is set to 2 or 3, a cabinet install is assumed. In this mode, the cabinet files are assumed to exist in the directory indicated by the SourceDir property. If the Source Type value is 0 or 1, all source files are assumed to exist in the tree whose root is indicated by the SourceDir property.

Note that this only applies to files in the File table that do not have either the Compressed or Uncompressed bits set in the attributes column. These bits override the value of the Word Count Summary property when determining if a particular file is compressed or uncompressed.


MIME Table

The MIME table associates a MIME content type with a file extension or a CLSID to generate the extension or COM server information required for advertisement of the MIME (Multipurpose Internet Mail Extensions) content.

The MIME table has the following columns.

Column | Type | Key | Nullable
ContentType | Text | Y | N
Extension_ | Text |  | N
CLSID | GUID |  | Y

Columns

ContentType
This column is an identifier for the MIME content. It is commonly written in the form of type/format.
Extension_
This column contains the server extension that is to be associated with the MIME content, without the dot. This column is a foreign key into the Extension table. The Extension table contains file extension server information which is used as a part of advertisement.
CLSID
This column contains the COM server CLSD that is to be associated with the MIME content. The CLSID in this column can be a foreign key into the Class table or it can be a CLSD that already exists on the user's machine. The Class table contains COM server-related information which is used as a part of advertisement.

Remarks

This table is referred to when the RegisterMIMEInfo action or the UnregisterMIMEInfo action is executed. In advertise mode, the RegisterMIMEInfo action registers all MIME information for servers from the MIME table for which the corresponding feature is enabled. Otherwise the action registers MIME information for servers from the MIME table for which the corresponding feature is currently selected to be installed. The UnregisterMIMEInfo action unregisters MIME-related registry information from the system. The action unregisters MIME information for servers from the MIME table for which the corresponding feature is currently selected to be uninstalled.


MoveFile Table

This table contains a list of files to be moved or copied from a specified source directory to a specified destination directory.

The MoveFile table has the following columns.

Column | Type | Key | Nullable
FileKey | Identifier | Y | N
Component_ | Identifier |  | N
SourceName | WildCardFilename |  | Y
DestName | Filename |  | Y
SourceFolder | Identifier |  | Y
DestFolder | Identifier |  | N
Options | Integer |  | N

Columns

FileKey
Primary key that uniquely identifies a particular MoveFile record.
Component_
External key into the Component table.. If the component referenced by this key is not selected for installation or removal, then no action is taken on this MoveFile entry.
SourceName
This column contains the localizable name of the source files to be moved or copied. This column may be left blank. See the description of the SourceFolder column. This field may contain wildcard characters (* and ?).
DestName
This column contains the localizable name to be given to the original file after it is moved or copied. If this field is blank, then the destination file is given the same name as the source file.
SourceFolder
This column contains the name of a property having a value that resolves to the full path to the source directory. If the SourceName column is left blank, then the property named in the SourceFolder column is assumed to contain the full path to the source file itself (including the file name).
DestFolder
The name of a property whose value resolves to the full path to the destination directory.
Options
Integer value specifying the operating mode.
Constant | Hexadecimal | Decimal | Meaning
(none) | 0x000 | 0 | Copy the source file.
msidbMoveFileOptionsMove | 0x001 | 1 | Move the source file.

Remarks

This table is processed by the MoveFiles action.


MsiDigitalCertificate Table

The MsiDigitalCertificate table stores certificates in binary stream format and associates each certificate with a primary key. The primary key is used to share certificates among multiple digitally signed objects. A digital certificate is a credential that provides a means to verify identity. For more information, see Digital Certificates in the Security section of the Microsoft® Platform Software Development Kit (SDK).

Windows Installer version 1.5 can only verify the digital signatures of external cabinets, and only by the use of MsiDigitalSignature table and MsiDigitalCertificate table. The MsiDigitalSignature and MsiDigitalCertificate tables are available with Windows Installer 1.5 and later versions.

Windows Installer version 1.5 uses digital signatures as a means to detect corrupted resources. A signer certificate may be compared to the signer certificate of an external resource to be installed by the package.

The MsiDigitalCertificate table has the following columns.

Column | Type | Key | Nullable
DigitalCertificate | Identifier | Y | N
CertData | Binary |  | N

Columns

DigitalCertificate
Identifies the digital signature certificate. Primary key of table
CertData
The binary representation of the digital certificate. The CertData column contains the encoded byte array of a certificate context. This is the pbCertEncoded member of the CERT_CONTEXT structure. The certificate context can be obtained by calling WinVerifyTrust, MsiGetFileSignatureInformation, or by importing a .cer file.

See Also

MsiGetFileSignatureInformation, MsiDigitalSignature table, Digital Signatures and Windows Installer


MsiDigitalSignature Table

The MsiDigitalSignature table contains the signature information for every digitally signed object in the installation database.

Windows Installer version 1.5 can only verify the digital signatures of external cabinets, and only by the use of MsiDigitalSignature and MsiDigitalCertificate tables. The MsiDigitalSignature table and MsiDigitalCertificate table are available with Windows Installer 1.5 and later versions.

Windows Installer version 1.5 uses digital signatures as a means to detect corrupted resources. A signer certificate may be compared to the signer certificate of an external resource to be installed by the package.

The MsiDigitalSignature table has the following columns.

Column | Type | Key | Nullable
Table | Identifier | Y | N
SignObject | Text | Y | N
DigitalCertificate_ | Identifier |  | N
Hash | Binary |  | Y

Columns

Table
With the Windows Installer version 1.5, the entry in this field must be "Media" for the Media table. The installer only verifies the digital signatures on external cabinet media entries. This column and the SignObject column together specify the resource that is digitally signed.
SignObject
A foreign key into the primary key of the table specified by the Table column. This column and the Table column together specify the resource that is digitally signed.
DigitalCertificate_
A foreign key into the MsiDigitalCertificate table. This identifies the certificate that must exist on the file for the associated action to succeed. The resource (or object) is always required to match this certificate in the MsiDigitalCertificate table.
Hash
In this field enter the reference hash of the resource (or object) that is to be checked against the actual hash of the resource (or object) obtained at run-time. If only the certificate needs to be verified, the Hash field may be NULL. Note that the format of the hash depends on the type of the resource (or object) being signed.

The Hash column contains the binary representation of the hash. The actual content is the pbData member of the CRYPT_HASH_BLOB structure. This may be obtained by calling WinVerifyTrust or MsiGetFileSignatureInformation.

See Also

MsiGetFileSignatureInformation, MsiDigitalCertificate table, Digital Signatures and Windows Installer


MsiFileHash Table

The MsiFileHash table is used to store a 128-bit hash of a source file provided by the Windows Installer package. The hash is split into four 32-bit values and stored in separate columns of the table.

The Windows Installer can use file hashing as a means to detect and eliminate unnecessary file copying. A file hash stored in the MsiFileHash table may be compared to a hash of an existing file on the user's computer obtained by calling MsiGetFileHash.

The MsiFileHash table has the following columns.

Column | Type | Key | Nullable
File_ | Identifier | Y | N
Options | Integer |  | N
HashPart1 | DoubleInteger |  | N
HashPart2 | DoubleInteger |  | N
HashPart3 | DoubleInteger |  | N
Hashpart4 | DoubleInteger |  | N

Columns

File_
Foreign key to File table. 72 char string.
Options
This column must be 0 and is reserved for future use.
HashPart1
First 32 bits of hash. The file hash entered in this field must be obtained by calling MsiGetFileHash or the FileHash method. Do not use other methods.
HashPart2
Second 32 bits of hash. The file hash entered in this field must be obtained by calling MsiGetFileHash or the FileHash method. Do not use other hashing methods.
HashPart3
Third 32 bits of hash. The file hash entered in this field must be obtained by calling MsiGetFileHash or the FileHash method. Do not use other methods.
HashPart3
Fourth 32 bits of hash. The file hash entered in this field must be obtained by calling MsiGetFileHash or the FileHash method. Do not use other methods.

See Also

MsiGetFileHash, Default File Versioning


ODBCAttribute Table

The ODBCAttribute table contains information about the attributes of ODBC drivers and translators.

The ODBCAttribute table has the following columns.

Column | Type | Key | Nullable
Driver_ | Identifier | Y | N
Attribute | Text | Y | N
Value | Text |  | Y

Columns

Driver_
Internal token name for a driver. A primary key for the table. A foreign key into the ODBCDriver table.
Attribute
Name of the driver attribute. A primary key for the table.
Value
Localizable string value for attribute.


ODBCDataSource Table

The ODBCDataSource table lists the data sources belonging to the installation.

The ODBCDataSource table has the following columns.

Column | Type | Key | Nullable
DataSource | Identifier | Y | N
Component_ | Identifier |  | N
Description | Text |  | N
DriverDescription | Text |  | N
Registration | Integer |  | N

Columns

DataSource
Internal token name for data source. A primary key for the table.
Component_
External key into the Component table.
Description
The description registered for this data source. This value cannot be localized.
DriverDescription
Associated driver which may be pre-existing. This value cannot be localized.
Registration
This field specifies the type of registration for the data source.
Constant | Hexadecimal | Decimal | Description
msidbODBCDataSourceRegistrationPerMachine | 0x000 | 0 | Data source is registered per machine.
msidbODBCDataSourceRegistrationPerUser | 0x001 | 1 | Data source is registered per user.


ODBCDriver Table

The ODBCDriver table lists the ODBC drivers belonging to the installation.

The ODBCDriver table has the following columns.

Column | Type | Key | Nullable
Driver | Identifier | Y | N
Component_ | Identifier |  | N
Description | Text |  | N
File_ | Identifier |  | N
File_Setup | Identifier |  | Y

Columns

Driver
Internal token name for driver. A primary key for the table
Component_
External key into the Component table.
Description
The description registered for this ODBC driver. This value cannot be localized.
File_
The DLL file for driver listed in the Driver column. This column is a key into the File table.
File_Setup
The setup DLL file for the driver if it is different than from Driver. This is a key into the File table.


ODBCSourceAttribute Table

The ODBCSourceAttribute table contains information about the attributes of data sources.

The ODBCSourceAttribute table has the following columns.

Column | Type | Key | Nullable
DataSource_ | Identifier | Y | N
Attribute | Text | Y | N
Value | Text |  | Y

Columns

DataSource_
Internal token name for data source. A primary key for the table.
Attribute
Name of data source attribute. A primary key for the table.
Value
The localizable string value for the attribute.


ODBCTranslator Table

The ODBCTranslator table lists the ODBC translators belonging to the installation.

The ODBCTranslator table has the following columns.

Column | Type | Key | Nullable
Translator | Identifier | Y | N
Component_ | Identifier |  | N
Description | Text |  | N
File_ | Identifier |  | N
File_Setup | Identifier |  | Y

Columns

Translator
Internal token name for translator. A primary key for the table.
Component_
External key into the Component table.
Description
The description registered for this ODBC driver translator. This value cannot be localized.
File_
The DLL file for the transfer listed in the Translator column. This column is a key into the File table.
File_Setup
The setup DLL file for the translator if it is different from the Translator column. This is a key into the File table.


Patch Table

The Patch table specifies the file that is to receive a particular patch and the physical location of the patch files on the media images.

The Patch table has the following columns.

Column | Type | Key | Nullable
File_ | Identifier | Y | N
Sequence | Integer | Y | N
PatchSize | DoubleInteger |  | N
Attributes | Integer |  | N
Header | Binary |  | N

Columns

File_
The patch is applied to the file specified by the identifier in this column. This is a primary key for the table and it is a foreign key to the File table.
Sequence
This is the position of the patch file in the sequence order of files on the media images. The sequence order must correspond to the order of the files in the patch package cabinet file. This is a primary key for this table.
PatchSize
This column gives the size of the patch in bytes written as a long integer.
Attributes
Integer containing bit flags representing patch attributes. Insert a value of 1 in this column to indicate that the failure to apply this patch is not a fatal error.
Constant | Hexadecimal | Decimal | Description
(none) | 0x000 | 0 | Failure to apply this patch is a fatal error.
msidbPatchAttributesNonVital | 0x001 | 1 | Indicates that the failure to apply this patch is not a fatal error.

Header
This column is the binary stream patch header used for patch validation.

Remarks

This table is processed by the PatchFiles action. It is usually added to the install package by a transform from a patch package. It is usually not authored directly into an install package.


PatchPackage Table

The PatchPackage table describes all patch packages that have been applied to this product. For each patch package, the unique identifier for the patch is provided along with information about the media image the on which the patch is located.

The PatchPackage table has the following columns.

Column | Type | Key | Nullable
PatchId | GUID | Y | N
Media_ | Integer |  | N

Columns

PatchId
This column contains a unique identifier for this particular patch.
Media_
This column is a foreign key to the DiskId column of the Media Table and indicates the disk containing the patch package.

Remarks

This table is usually added to the install package by a transform from a patch package. It is usually not authored directly into an install package.


ProgId Table

The ProgId table contains information for program IDs and version independent program IDs that must be generated as a part of the product advertisement.

The ProgId table has the following columns.

Column | Type | Key | Nullable
ProgId | Text | Y | N
ProgId_Parent | Text |  | Y
Class_ | GUID |  | Y
Description | Text |  | Y
Icon_ | Identifier |  | Y
IconIndex | Integer |  | Y

Columns

ProgId
The program ID or version independent program ID.
ProgId_Parent
Defined only for version independent program IDs. This field is a foreign key into the ProgId column. To define a version independent program ID, enter the corresponding ProgId into the ProgId_Parent column.
Class_
An optional foreign key into the Class table. This column must be Null for a version independent ProgId.
Description
An optional localized description of the associated program ID.
Icon_
An optional foreign key into the Icon table that specifies the icon file associated with this ProgId. This is written under the DefaultIcon key associated with this ProgId. This column must be Null for a version independent ProgId.
IconIndex
The Icon index into the icon file. This column must be Null for a version independent ProgId.


Property Table

The Property table contains the property names and values for all defined properties in the installation. Properties with Null values are not present in the table.

The Property table has the following columns.

Column | Type | Key | Nullable
Property | Identifier | Y | N
Value | Text |  | N

Columns

Property
The name of a property. See Properties.
Value
A localizable string value for the property. This may never be Null or an empty string.

Remarks

Note that you cannot use the Property table to set a property to the value of another property. The installer does nothing to the text string entered in the Value column before setting the property in the Property column. If FirstProperty is entered into the Property column and [SecondProperty] in the Value column, the value of FirstProperty is set to the text string "[SecondProperty]" and not to the value of the SecondProperty property. This is necessary to prevent creating circular references in the Property table. Instead, you can set one property to another by using a Custom Action Type 51.

Note that the AdminProperties property can be used to override the values in the Property table during an Administrative Installation.

Do not use properties for passwords or other information that must remain secure. The installer may write the value of a property authored into the Property table, or created at runtime, into a log or the system registry.


PublishComponent Table

The PublishComponent table associates components listed in the Component table with a qualifier text-string and a category ID GUID. Components with parallel functionality that have been grouped together in this way are referred to as qualified components. See Qualified Components. This provides the installer with a method for single-level indirection when referring to components. See Using Qualified Components.

The PublishComponent table has the following columns.

Column | Type | Key | Nullable
ComponentId | GUID | Y | N
Qualifier | Text | Y | N
Component_ | Identifier | Y | N
AppData | Text |  | Y
Feature_ | Identifier |  | N

Columns

ComponentId
A string GUID that represents the category of components being grouped together. Note that this column's title is misleading. This is the GUID for the category of qualified components and is not the same GUID appearing in the ComponentId column of the Component table. Here it refers to a server that provides the functionality of a component to external clients rather than the component itself.
Qualifier
A text string that qualifies the value in the ComponentId column. A qualifier is used to distinguish multiple forms of the same component, such as a component that is implemented in multiple languages. These are the qualifier text-strings returned by MsiEnumComponentQualifiers.
Component_
External key into column one of the Component table. This identifier refers to the qualified component's record in the Component table.
AppData
An optional localizable text describing the qualified component of this record. The string is commonly parsed by the application and can be displayed to the user. It should describe the qualified component. This can be retrieved with MsiEnumComponentQualifiers.
Feature_
External key into column one of the Feature table. This is the feature using this qualified component.

Remarks

This table is referred to when the PublishComponents action or the UnpublishComponents action is executed.

Note that the name of this table is misleading. This table is not required in order to author advertisement. See the Attributes column of the Component table and Feature table for information on how to set the installation state of components to advertise.


RadioButton Table

Radio buttons are not treated as individual controls, but they are part of a radio button group that functions as a control. The RadioButton table lists the buttons for all the groups.

The RadioButton table has the following columns.

Column | Type | Key | Nullable
Property | Identifier | Y | N
Order | Integer | Y | N
Value | Formatted |  | N
X | Integer |  | N
Y | Integer |  | N
Width | Integer |  | N
Height | Integer |  | N
Text | Formatted |  | Y
Help | Text |  | Y

Columns

Property
A named property to be tied to this radio button. All the buttons tied to the same property become part of the same group.
Order
A positive integer used to determine the ordering of the items within one list. The integers do not have to be consecutive.
Value
The value string associated with this button. Selecting the button sets the associated property to this value.
X
The horizontal coordinate within the group of the upper-left corner of the bounding rectangle of the radio button. This must be a non-negative number.
Y
The vertical coordinate within the group of the upper-left corner of the bounding rectangle of the radio button. This must be a non-negative number.
Width
The width of the button. This must be a non-negative number.
Height
The height of the button. This must be a non-negative number.
Text
The localizable, visible title to be assigned to the radio button. If the text is too long to be fit on the control, then it is truncated. If the button displays an icon or a bitmap, then this column contains the name of the picture, which is a key into the Binary table. There is no way to show both a picture and text on a button.
Help
The Help strings used with the button. The text is optional and is localizable. The string is divided into two parts separated by a character (|). The first part of the string is used as ToolTip text. This text is shown by screen readers for controls that contain a picture. The second part is used for context-sensitive Help, although context-sensitive help has not yet been implemented. The separator character is required even if only one of the two kinds of text is present.

Remarks

The integer values for x, y, width, and height are in the installer units, not dialog units. An installer unit is equal to one-twelfth the height of the 10-point MS Sans Serif font size. Coordinates for the controls are relative to the billboard.

The coordinates of the buttons are given relative to the group. If the coordinates of the group are changed, then the buttons within the group remain in the same relative position to each other.

The contents of the Value and Text fields are formatted by the MsiFormatRecord function when the control is created, therefore they can contain any expression that the MsiFormatRecord function can interpret. The formatting occurs only when the control is created, and it is not updated if a property involved in the expression is modified during the life of the control.

Note that the focus on a dialog box will not tab to a RadioButtonGroup Control until one of the buttons in the group has been selected. To make the focus tab to this button group specify one of the buttons as a default setting for the control.


Registry Table

The Registry table holds the registry information that the application needs to set in the system registry.

The Registry table has the following columns.

Column | Type | Key | Nullable
Registry | Identifier | Y | N
Root | Integer |  | N
Key | RegPath |  | N
Name | Formatted |  | Y
Value | Formatted |  | Y
Component_ | Identifier |  | N

Columns

Registry
Primary key used to identify a registry record.
Root
The predefined root key for the registry value. Enter a value of -1 in this field to make the root key dependent on the type of installation. Enter one of the other values in the following table to force the registry value to be written under a particular root key.
Constant | Hexadecimal | Decimal | Root key
(none) - 0x001 -1 If this is a per-user installation, the registry value is written under HKEY_CURRENT_USER.

If this is a per-machine installation, the registry value is written under HKEY_LOCAL_MACHINE. Note that a per-machine installation is specified by setting the ALLUSERS property to 1.
msidbRegistryRootClassesRoot 0x000 0 HKEY_CLASSES_ROOT

When using Windows 2000 or later, the installer writes or removes the value from the HKCU\Software\Classes hive during for per-user installations.

When using Windows 2000 or later operating systems, the installer writes or removes the value from the HKLM\Software\Classes hive during for per-machine installations.
msidbRegistryRootCurrentUser | 0x001 | 1 | HKEY_CURRENT_USER
msidbRegistryRootLocalMachine | 0x002 | 2 | HKEY_LOCAL_MACHINE
msidbRegistryRootUsers | 0x003 | 3 | HKEY_USERS

Note that it is recommended that registry entries written to the HKCU hive reference a component having the RegistryKeyPath bit is set in the Attributes column of the Component table. This ensures that the installer writes the necessary registry entries when there are multiple users on the same computer.

Key
The localizable key for the registry value.
Name
This column contains the registry value name (localizable). If this is Null, then the data entered into the Value column are written to the default registry key.

If the Value column is Null, then the strings shown in the following table in the Name column have special significance.
String Meaning
+ The key is to be created, if absent, when the component is installed.
- The key is to be deleted, if present, with all of its values and subkeys, when the component is uninstalled.
* The key is to be created, if absent, when the component is installed. Additionally, the key is to be deleted, if present, with all of its values and subkeys, when the component is uninstalled.

Note that the RemoveRegistry table must be use if an installed registry key is to be deleted, with its values and subkeys, when the component is installed.

Value
This column is the localizable registry value. The field is Formatted. If the Value is prefixed by a number sign (#) then the value is interpreted as follows.
String | Meaning
#x | The value is interpreted and stored as a hexadecimal value (REG_BINARY).
#% The value is interpreted and stored as an expandable string (REG_EXPAND_SZ).
# The value is interpreted and stored as an integer (REG_DWORD).

  • If the value contains the sequence tilde [~], then the value is interpreted as a Null-delimited list of strings (REG_MULTI_SZ). For example, to specify a list containing the three strings a, b and c, use "a[~]b[~]c."
  • The sequence [~] within the value separates the individual strings and is interpreted and stored as a Null character.
  • If a [~] precedes the string list, the strings are to be appended to any existing registry value strings. If an appending string already occurs in the registry value, the original occurrence of the string is removed.
  • If a [~] follows the end of the string list, the strings are to be prepended to any existing registry value strings. If a prepending string already occurs in the registry value, the original occurrence of the string is removed.
  • If a [~] is at both the beginning and the end or at neither the beginning nor the end of the string list, the strings are to replace any existing registry value strings.
  • Otherwise, the value is interpreted and stored as a string (REG_SZ).
  • If the value begins with two or more consecutive number signs (#), the value is interpreted and stored as a string, ignoring the first #.
Component_
External key into the first column of the Component table referencing the component that controls the installation of the registry value.

Remarks

The registry information is written out to the system registry when the corresponding component has been selected to be installed locally or run from source.

Note that the installer removes a registry key after removing the last value or subkey under the key. To prevent an empty registry key from being removed when uninstalling, write a dummy value under the key you need to keep and enter + in the Name column.

This table is referred to when the WriteRegistryValues action is executed.

For information on how to secure a registry key see the LockPermissions Table.


RegLocator Table

The RegLocator table holds the information needed to search for a file or directory using the registry, or to search for a particular registry entry itself. This table has the following columns.

Column | Type | Key | Nullable
Signature_ | Identifier | Y | N
Root | Integer |  | N
Key | RegPath |  | N
Name | Formatted |  | Y
Type | Integer |  | Y

Columns

Signature_
The value in the Signature_ field represents a unique signature that is an external key into column one of the Signature table. If this signature is present in the Signature table, the search is for a file. If this signature is absent from the Signature table, and the value of the Type column is msidbLocatorTypeRawValue, the search is for the registry key name pointed to by the RegLocator table. Otherwise the search is for a directory pointed to by the RegLocator table.
Root
The predefined root key for the registry value.
Constant | Hexadecimal | Decimal | Root key
msidbRegistryRootClassesRoot | 0x000 | 0 | HKEY_CLASSES_ROOT
msidbRegistryRootCurrentUser | 0x001 | 1 | HKEY_CURRENT_USER
msidbRegistryRootLocalMachine | 0x002 | 2 | HKEY_LOCAL_MACHINE
msidbRegistryRootUsers | 0x003 | 3 | HKEY_USERS

Key
The key for the registry value.
Name
The registry value name.
Type
A value that determines if the registry value is a file name, a directory location, or raw registry value.

The following table lists valid values. Set one of the first three values and msidbLocatorType64bit if necessary. If the entry in this field is absent, Type is set to be 1.
Constant | Hexadecimal | Decimal | Description
msidbLocatorTypeDirectory | 0x000 | 0 | Key path is a directory.
msidbLocatorTypeFileName | 0x001 | 1 | Key path is a file name.
msidbLocatorTypeRawValue | 0x002 | 2 | Key path is a registry value.
msidbLocatorType64bit 0x010 4 Set this bit to have the installer search the 64-bit portion of the registry.

Leave this bit unset to have the installer search the 32-bit portion of the registry.

Remarks

This table is used with the AppSearch Table.

This table's columns are generally not localized. If an author decides to search for products in multiple languages, then there must be a separate entry included in the table for each language.

For more information, see Searching for Existing Applications, Files, Registry Entries or .ini File Entries.


RemoveFile Table

The RemoveFile table contains a list of files to be removed by the RemoveFiles action. Setting the FileName column of this table to Null supports the removal of empty folders.

The RemoveFile table has the following columns.

Column | Type | Key | Nullable
FileKey | Identifier | Y | N
Component_ | Identifier |  | N
FileName | WildCardFilename |  | Y
DirProperty | Identifier |  | N
InstallMode | Integer |  | N

Columns

FileKey
Primary key used to identify this particular table entry.
Component_
External key the first column of the Component table. This field references the component that controls the file to be removed.
FileName
This column contains the localizable name of the file to be removed. If this column is null, then the specified folder will be removed if it is empty. All of the files that match the wildcard will be removed from the specified directory.
DirProperty
Name of a property whose value is assumed to resolve to the full path to the folder of the file to be removed. The property can be the name of a directory in the Directory table, a property set by the AppSearch table, or any other property that represents a full path.
InstallMode
Must be one of the following values.
Constant | Hexadecimal | Decimal | Description
msidbRemoveFileInstallModeOnInstall | 0x001 | 1 | Remove only when the associated component is being installed (msiInstallStateLocal or msiInstallStateSource).
msidbRemoveFileInstallModeOnRemove | 0x002 | 2 | Remove only when the associated component is being removed (msiInstallStateAbsent).
msidbRemoveFileInstallModeOnBoth | 0x003 | 3 | Remove in either of the above cases.

Remarks

The file references in this table are processed by the RemoveFiles action.


RemoveIniFile Table

The RemoveIniFile table contains the information an application needs to delete from a .ini file.

The RemoveIniFile table has the following columns.

Column | Type | Key | Nullable
RemoveIniFile | Identifier | Y | N
FileName | Text |  | N
DirProperty | Identifier |  | Y
Section | Formatted |  | N
Key | Formatted |  | N
Value | Formatted |  | Y
Action | Integer |  | N
Component_ | Identifier |  | N

Columns

RemoveIniFile
The key for this table.
FileName
The .ini file name in which to delete the information.
DirProperty
Name of a property whose value is assumed to resolve to the full path to the folder of the .ini file to be removed. The property can be the name of a directory in the Directory table, a property set by the AppSearch table, or any other property that represents a full path.
Section
The localizable .ini file section.
Key
The localizable .ini file key below the section.
Value
The localizable value to be deleted. The value is required when Action is 4.
Action
The type of modification to be made.
Constant | Hexadecimal | Decimal | Meaning
msidbIniFileActionRemoveLine | 0x002 | 2 | Deletes .ini entry.
msidbIniFileActionRemoveTag | 0x004 | 4 | Deletes a tag from a .ini entry.

Component_
External key into first column of the Component table referencing the component that controls the deletion of the .ini value.

Remarks

The .ini file information is deleted when the corresponding Component has been selected to be installed, either locally or run from source.

This table is referred to when the RemoveIniValues action is executed.

If the Directory_ column is specified as null, the ini file location is the standard Windows ini location which is the Windows directory by default.

Removing the last value from a section deletes that section. There is no other way to delete an entire section other than removing all its values.


RemoveRegistry Table

The RemoveRegistry table contains the registry information the application needs to delete from the system registry.

The RemoveRegistry table has the following columns.

Column | Type | Key | Nullable
RemoveRegistry | Identifier | Y | N
Root | Integer |  | N
Key | RegPath |  | N
Name | Formatted |  | Y
Component_ | Identifier |  | N

Columns

RemoveRegistry
The key for this table.
Root
The predefined root key for the registry value.
Constant | Hexadecimal | Decimal | Root key
(none) - 0x001 -1 HKEY_CURRENT_USER

Installer sets this key while doing a per-user installation.
(none) -0x001 -1 HKEY_LOCAL_MACHINE

Installer sets this key while doing an all-users installation with ALLUSERS set to 1.
msidbRegistryRootClassesRoot | 0x000 | 0 | HKEY_CLASSES_ROOT
msidbRegistryRootCurrentUser | 0x001 | 1 | HKEY_CURRENT_USER
msidbRegistryRootLocalMachine | 0x002 | 2 | HKEY_LOCAL_MACHINE
msidbRegistryRootUsers | 0x003 | 3 | HKEY_USERS

Key
The localizable key for the registry value.
Name
The localizable registry value name.

The following string in the Name column have special significance.
String Meaning
"-" The key is to be deleted, if present, with all of its values and subkeys, when the component is installed.

Note that the Registry table should be used to create or remove a registry key when the component is removed.

Component_
External key into the first column of the Component table referencing the component that controls the deletion of the registry value.

Remarks

The registry information is deleted from the system registry when the corresponding component has been selected to be installed locally or run from source.

This table is referred to when the RemoveRegistryValues action is executed.


ReserveCost Table

The ReserveCost table is an optional table that allows the author to reserve an amount of disk space in any directory that depends on the installation state of a component.

The ReserveCost table has the following columns.

Column | Type | Key | Nullable
ReserveKey | Identifier | Y | N
Component_ | Identifier |  | N
ReserveFolder | Identifier |  | Y
ReserveLocal | DoubleInteger |  | N
ReserveSource | DoubleInteger |  | N

Columns

ReserveKey
Primary key that uniquely identifies a ReserveCost table entry.
Component_
External key to column one of the Component Table. Reserves a specified amount of space if this component is to be installed.
ReserveFolder
This column contains the name of a property that is the full path to the destination directory. This property name is typically the name of a directory in the Directory table or the name of a property set obtained using the Appsearch action. This adds the amount of disk space specified in ReserveLocal or ReserveSource to the volume cost of the device containing the directory.
ReserveLocal
The number of bytes of disk space to reserve if the linked component is installed to run locally.
ReserveSource
The number of bytes of disk space to reserve if the linked component is installed to run from source.

Remarks

Reserving cost in this way could be useful for authors who want to ensure that a minimum amount of disk space will be available after the installation is completed. For example, this disk space might be reserved for user documents or for application files (such as index files) that are created only after the application is started following installation. The ReserveCost table also allows custom actions to specify an approximate cost for any files, registry entries, or other items that the custom action might install.


SelfReg Table

The SelfReg table contains information about modules that need to be self-registered. The installer calls the DllRegisterServer() function at the time of installing the module and the DllUnregisterServer() function at the time of uninstalling the module. The installer does not self-register EXE files.

The SelfReg table has the following columns.

Column | Type | Key | Nullable
File_ | Identifier | Y | N
Cost | Integer |  | Y

Columns

File_
External key into the first column of the File table indicating the module that needs to be registered.
Cost
The cost of registering the module in bytes. This must be a non-negative number.

Remarks

It is strongly recommended that installation package authors not use self-registration. Instead they should register modules by authoring one or more of the other tables provided by the installer for this purpose. See Registry Tables Group. Many of the benefits of having a central installer service are lost with self-registration because self-registration routines tend to hide critical configuration information.

  • A rollback of an installation with self-registered modules cannot be safely done using DllUnregisterServer because there is no way of telling if the self-registered keys are used by another feature or application.
  • The ability to use advertisement is reduced if Class or extension server registration is performed within self-registration routines.
  • The installer automatically handles HKCR keys in the registry tables for both per-user or per-machine installations. DllRegisterServer routines currently do not support the notion of a per-user HKCR key.
  • If multiple users are using a self-registered application on the same computer, each user must install the application the first time they run it. Otherwise the installer cannot easily determine that the proper HKCU registry keys exist.
  • The DLLRegisterServer can be denied access to network resources such as type libraries if a component is both specified as run-from-source and is listed in the SelfReg table. This can cause the installation of the component to fail to during an administrative installation.
  • Self-registering DLLs are more susceptible to coding errors because the new code required for DllRegisterServer is commonly different for each DLL. Instead use the registry tables in the database to take advantage of existing code provided by the installer.
  • Self-registering DLLs can sometimes link to auxiliary DLLs that are not present or are the wrong version. In contrast, the installer can register the DLLs using the registry tables with no dependency on the current state of the system.

Note You cannot specify the order in which the installer registers or unregisters self-registering DLLs by using the SelfRegModules and SelfUnRegModules actions. See Specifying the Order of Self Registration.


ServiceControl Table

The ServiceControl table is used to control installed or uninstalled services.

The ServiceControl table has the following columns.

Column | Type | Key | Nullable
ServiceControl | Identifier | Y | N
Name | Formatted |  | N
Event | Integer |  | N
Arguments | Formatted |  | Y
Wait | Integer |  | Y
Component_ | Identifier |  | N

Columns

ServiceControl
This is the primary key of this table.
Name
This column is the string naming the service. This column can be used to control a service that is not installed.
Event
This column contains the operations to be performed on the named service. Note that when stopping a service, all services that depend on that service are also stopped. When deleting a service that is running, the installer stops the service.

The values in this field are bitfields that can be combined into a single value that represents several operations.

The following values are only used during an installation.
Constant | Hexadecimal | Decimal | Description
msidbServiceControlEventStart | 0x001 | 1 | Starts the service during the StartServices action.
msidbServiceControlEventStop | 0x002 | 2 | Stops the service during the StopServices action.
(none) | 0x004 | 4 | <reserved>
msidbServiceControlEventDelete | 0x008 | 8 | Deletes the service during the DeleteServices action.

The following values are only used during an uninstall.
Constant | Hexadecimal | Decimal | Description
msidbServiceControlEventUninstallStart | 0x010 | 16 | Starts the service during the StartServices action.
msidbServiceControlEventUninstallStop | 0x020 | 32 | Stops the service during the StopServices action.
(none) | 0x040 | 64 | <reserved>
msidbServiceControlEventUninstallDelete | 0x080 | 128 | Deletes the service during the DeleteServices action.

Arguments
A list of arguments for starting services. The arguments are separated by null characters [~]. For example, the list of arguments One, Two, and Three are listed as: One[~]Two[~]Three.
Wait
A value of 1 in this column (or leaving the column NULL) means to wait until the service actually completes before proceeding. This implies that the event is critical to the install, and that if the event fails the resulting error cannot be ignored. A value of 0 in this column means to wait only until the service control manager (SCM) reports that this service is in a pending state.
Component_
External key to column one of the Component Table.

Remarks

Use the Name column to start, stop, or delete services that are being replaced by the installation or that are dependent upon a new service that is being installed. For example, entering MyService into the ServiceControl column can tie this service to MyComponent in the Component_ column. If the bit field in the Event column is set for start while installing, then the installer will start MyService when installing MyComponent.


ServiceInstall Table

The ServiceInstall table is used to install a service and has the following columns.

Column | Type | Key | Nullable
ServiceInstall | Identifier | Y | N
Name | Formatted |  | N
DisplayName | Formatted |  | Y
ServiceType | DoubleInteger |  | N
StartType | DoubleInteger |  | N
ErrorControl | DoubleInteger |  | N
LoadOrderGroup | Formatted |  | Y
Dependencies | Formatted |  | Y
StartName | Formatted |  | Y
Password | Formatted |  | Y
Arguments | Formatted |  | Y
Component_ | Identifier |  | N
Description | Formatted |  | Y

Columns

ServiceInstall
This is the primary key for the table.
Name
This column is the string that gives the service name to install. The string has a maximum length of 256 characters. The service control manager database preserves the case of the characters in the service name, but comparisons of service names are case insensitive. Forward-slash (/) and back-slash (\) are invalid service name characters.
DisplayName
This column is the localizable string that user interface programs use to identify the service. The string has a maximum length of 256 characters. The service control manager preserves the case of the display name, but display name comparisons are case insensitive.
ServiceType
This column is a set of bit flags that specify the type of service. One of the following service types must be specified in this column.
Type of service | Value | Description
SERVICE_WIN32_OWN_PROCESS | 0x00000010 | A Microsoft Win32® service that runs its own process.
SERVICE_WIN32_SHARE_PROCESS | 0x00000020 | A Win32 service that shares a process.
SERVICE_INTERACTIVE_PROCESS | 0x00000100 | A Win32 service that interacts with the desktop. This value cannot be used alone and must be added to one of the two previous types.

The following types of service are unsupported.
Type of service | Value | Description
SERVICE_KERNEL_DRIVER | 0x00000001 | A driver service.
SERVICE_FILE_SYSTEM_DRIVER | 0x00000002 | A file system driver service.

StartType
This column is a set of bit flags that specify when to start the service. One of the following types of service start must be specified in this column.
Type of service start | Value | Description
SERVICE_AUTO_START | 0x00000002 | A service start during startup of the system.
SERVICE_DEMAND_START | 0x00000003 | A service start when the service control manager calls the StartService function.
SERVICE_DISABLED | 0x00000004 | Specifies a service that can no longer be started.

The following types of service starts are valid only for driver services.
Type of driver service start | Value | Description
SERVICE_BOOT_START | 0x00000000 | A device driver started by the operating system loader.
SERVICE_SYSTEM_START | 0x00000001 | A device driver started by calling the IoInitSystem function. Use this in the ServiceControl Table, with the StartServices action put after the InstallServices action, to start a driver service during an install.

ErrorControl
This column specifies the action taken by the startup program if the service fails to start during startup. These values affect the ServiceControl StartService events for installed services. One of the following error control flags must be specified in this column.

Adding the constant msidbServiceInstallErrorControlVital (value = 0x08000) to the flags in the following table specifies that the overall install should fail if the service cannot be installed into the system.
Error control flag | Value | Startup program's action
SERVICE_ERROR_IGNORE | 0x00000000 | Logs the error and continues with the startup operation.
SERVICE_ERROR_NORMAL | 0x00000001 | Logs the error, displays a message box and continues the startup operation.
SERVICE_ERROR_CRITICAL | 0x00000003 | Logs the error if it is possible and the system is restarted with the last configuration known to be good. If the last-known-good configuration is being started, the startup operation fails.

LoadOrderGroup
This column contains the string that names the load ordering group of which this service is a member. Specify NULL or an empty string if the service does not belong to a group.
Dependencies
This column is a list of names of services or load ordering groups that the system must start before this service. Separate names in the list by Nulls. If the service has no dependencies, then specify Null or an empty string. Use the syntax [~] to insert a Null. Dependency on a group means that this service can run if at least one member of the group is running after an attempt to start all members of the group.

For example, to require that the system start service1 and service2, before starting the service listed in the ServiceInstall column, enter service1[~]service2[~][~] into the Dependencies column. The identifiers service1 and service2 must either occur in the primary key of the table or be the name of the service that is already installed.

You must prefix group names with + so that they can be distinguished from a service name. To require that the system start service1 and at least one member of the ordering group MyGroup before starting the service listed in the ServiceInstall column, enter service1[~]+MyGroup[~][~].

StartName
The service is logged on as the name given by the string in this column. If the service type is SERVICE_WIN32_OWN_PROCESS use an account name in the form: DomainName\UserName. If the account belongs to the built-in domain it is permitted to specify .\UserName. The LocalSystem account must be used if the type of service is SERVICE_WIN32_SHARE_PROCESS. The CreateService function uses the LocalSystem account if StartName is specified as NULL and most services will therefore leave this column blank.
Password
This string is the password to the account name in the IpServiceStartName parameter. Note that the user must have permissions to log on as a service. The service has no password if the pointer in IpServiceStartName is NULL or if it points to an empty string. The Startname of LocalSystem is NULL, and therefore the password for lpServiceStartName in this instance is NULL, so most services will leave this column blank.

Note that after deleting a service that was installed with a user name and password, the installer cannot rollback the service without first using a custom action to get the password. The installer can acquire all the necessary information about the service except the password, which is stored in a protected part of the system. The custom action acquires the password by prompting the user, reading a property from the database, or reading a file. The custom action must then call ChangeServiceConfig, to supply the password, before reinstalling the service.

Arguments
This column contains any command line arguments or properties required to run the service.
Component_
External key to column one of the Component Table. Note that to install this service using the InstallService table, the KeyPath for this component must be the executable file for the service.
Description
This column contains a localizable description for the service being configured. If this column is left blank the installer uses the existing description of the service if one exists. For more information, see SERVICE_DESCRIPTION in the Platform SDK. To erase an existing description enter "[~]" in this column. This results in a blank description for either a new or existing service. This column is not available with Windows Installer version 1.0.

Remarks

This table has most of the parameters to the Win32 CreateService function.

Although it is possible to use the user interface to specify that a service be installed as run-from-source, the installer does not actually support this type of installation. Services that run with the privilege level of the local system must be installed to run from the local hard drive. Avoid installing services that impersonate the privileges of a particular user because this may write security data into a log or the system registry. This can potentially create a security problem, password conflict, or the loss of configuration data when the system is restarted.


SFPCatalog Table

The SFPCatalog table contains the catalogs used by Windows Millennium Edition for Windows File Protection on Windows Millennium Edition.

The SFPCatalog table has the following columns.

Column | Type | Key | Nullable
SFPCatalog | Filename | Y | N
Catalog | Binary |  | N
Dependency | Formatted |  | Y

Columns

SFPCatalog
The short file name for the catalog. Because catalogs have no version, the catalog specified in this column can overwrite a catalog that has the same name and is already installed on the local system. See the file versioning topic Neither File Has a Version.
Catalog
Binary data for the catalog.
Dependency
The catalog specified in this field is the parent of the dependent catalog specified in the SFPCatalog field. Enter the short file name of the parent catalog into the Dependency field. This field is a key back into the SFPCatalog column. The dependency match is case sensitive.

If the Dependency field references another record in this SFPCatalog table, the parent catalog is installed before the dependent catalog.

If the Dependency field references a parent catalog that is not present in the SFPCatalog field of this table, and if the parent catalog is not already installed, the installation fails.

Remarks

This feature is not available in Windows Installer versions 1.0 or 1.1.

Windows File Protection for Windows Millennium Edition is provided with Windows Installer version 1.2. For more information see Windows File Protection on Windows Millennium Edition.

The InstallSFPCatalogFile action queries the Component table, File table, FileSFPCatalog table and SFPCatalog table.


Shortcut Table

The Shortcut table holds the information the application needs to create shortcuts on the user's computer.

The Shortcut table has the following columns.

Column | Type | Key | Nullable
Shortcut | Identifier | Y | N
Directory_ | Identifier |  | N
Name | Filename |  | N
Component_ | Identifier |  | N
Target | Shortcut |  | N
Arguments | Formatted |  | Y
Description | Text |  | Y
Hotkey | Integer |  | Y
Icon_ | Identifier |  | Y
IconIndex | Integer |  | Y
ShowCmd | Integer |  | Y
WkDir | Identifier |  | Y

Columns

Shortcut
The key value for this table.
Directory_
External key into the first column of the Directory table. This column specifies the directory in which the Shortcut file is created.
Name
The localizable name of the shortcut to be created.
Component_
External key into the first column of the Component table. The installer uses the installation state of the component specified in this column to determine whether the shortcut is created or deleted. This component must have a valid key path for the shortcut to be installed. If the Target column contains the name of a feature, the file launched by the shortcut is the key file of the component listed in this column.
Target
The shortcut target.

For an advertised shortcut, this column must be an external key into the first column of the Feature table. The installer evaluates the entry in the Target field as an Identifier and the entry must be a valid foreign key into the Feature Table. The file launched by the shortcut in this case is the key file of the component listed in the Component_ column. When the shortcut is activated, the installer verifies that all the components in the feature are installed before launching this file.

For a non-advertised shortcut, the installer evaluates this field as a Formatted string. The field should contains a property identifier enclosed by square brackets ([ ]), that is expanded into the file or a folder pointed to by the shortcut. For more information, see the CreateShortcuts action.

Arguments
The command-line arguments for the shortcut.

Note that the resolution of properties in the Arguments field is limited. A property formatted as [Property] in this field can only be resolved if the property already has the intended value when the component owning the shortcut is installed. For example, for the argument "[#MyDoc.doc]" to resolve to the correct value, the same process must be installing the file MyDoc.doc and the component that owns the shortcut.

Description
The localizable description of the shortcut.
Hotkey
The hotkey for the shortcut. The low-order byte contains the virtual-key code for the key, and the high-order byte contains modifier flags. This must be a non-negative number. Authors of installation packages are generally recommend not to set this option, because this can add duplicate hotkeys to a users desktop. In addition, the practice of assigning hotkeys to shortcuts can be problematic for users using hotkeys for accessibility.
Icon_
External key to column one of the Icon table.
IconIndex
The icon index for the shortcut. This must be a non-negative number.
ShowCmd
The Show command for the application window.

The following values may be used. The values are as defined for the Windows API function ShowWindow.
Value | Meaning
1 | SW_SHOWNORMAL
3 | SW_SHOWMAXIMIZED
7 | SW_SHOWMINNOACTIVE

WkDir
The name of the property that has the path of the working directory for the shortcut.

Remarks

Enabling a feature creates an advertised shortcut only if the system's IShellLink interface supports installer descriptor resolution. This is supported by Microsoft® Windows 2000, Microsoft® Windows® 98, and systems running Microsoft® Internet Explorer 4.01. If unsupported, the installer creates a non-advertised shortcut upon installation of the feature's component, either locally or run from source.

This table is referred to when the CreateShortcuts action and the RemoveShortcuts action is executed.

See also DISABLEADVTSHORTCUTS Property.


Signature Table

The Signature table holds the information that uniquely identifies a file signature.

The Signature table has the following columns.

Column | Type | Key | Nullable
Signature | Identifier | Y | N
FileName | Text |  | N
MinVersion | Text |  | Y
MaxVersion | Text |  | Y
MinSize | DoubleInteger |  | Y
MaxSize | DoubleInteger |  | Y
MinDate | DoubleInteger |  | Y
MaxDate | DoubleInteger |  | Y
Languages | Text |  | Y

Columns

Signature
The Signature column is a unique file signature.
FileName
The name of the file.
MinVersion
The minimum version of the file. If this field is specified, then the file must have a version that is at least equal to MinVersion.
MaxVersion
The maximum version of the file. If this field is specified, then the file must have a version that is at most equal to MaxVersion.
MinSize
The minimum size of the file. If this field is specified, then the file under inspection must have a size that is at least equal to MinSize. This must be a non-negative number.
MaxSize
The maximum size of the file. If this field is specified, then the file under inspection must have a size that is at most equal to MaxSize. This must be a non-negative number.
MinDate
The minimum creation date of the file. If this field is specified, then the file under inspection must have a creation date that is at least equal to MinDate. This must be a non-negative number.
MaxDate
The maximum creation date of the file. If this field is specified, then the file under inspection must have a creation date that is at most equal to MaxDate. This must be a non-negative number.
Languages
The languages supported by the file.

Remarks

This table is used with the AppSearch Table.

The signature is searched for using the RegLocator table, the IniLocator table, the CompLocator table, and the DrLocator table. This table's columns are generally not localized. If an author decides to search for products in multiple languages, then there can be a separate entry included in the table for each language.

The entries in the MinDate and MaxDate columns must be in the MS-DOS® date format, as shown in the following table.

Bits | Contents
0-4 | Day of the month (1-31)
5-8 | Month (1 = January, 2 = February, and so on)
9-15 | Year offset from 1980 (add 1980 to get actual year)


TextStyle Table

The TextStyle table lists different font styles used in controls having text.

The TextStyle table has the following columns.

Column | Type | Key | Nullable
TextStyle | Identifier | Y | N
FaceName | Text |  | N
Size | Integer |  | N
Color | DoubleInteger |  | Y
StyleBits | Integer |  | Y

Columns

TextStyle
This column is the name of the font style. This name can be embedded in the text string to indicate a style change. Note that the font style name used in this field must not end with the characters: _UL. See Adding Controls and Text.
FaceName
A string indicating the name of the font. The string must be no more than 31 characters long.
Size
The font size in installer units. An installer unit is equal to one-twelfth the height of the 10-point MS Sans Serif font size. This must be a non-negative number.
Color
This column specifies the text color displayed by a Text Control. All other types of controls always use the default text color. The value put in this column should be computed using the following formula: 65536 * blue + 256 * green + red, where red, green, and blue are each in the range of 0-255. The value must not exceed 16777215, which is the value for white. The value is 0 for black, 255 for red, 65280 for green, 16711680 for blue and 8421504 for grey. Leaving the field empty specifies the default color.
StyleBits
A combination of bits indicating the formatting for the text.

The individual style bits have the following values.
Constant | Hexadecimal | Decimal | Style
msidbTextStyleStyleBitsBold | 0x001 | 1 | Bold
msidbTextStyleStyleBitsItalic | 0x002 | 2 | Italic
msidbTextStyleStyleBitsUnderline | 0x002 | 4 | Underline
msidbTextStyleStyleBitsStrike | 0x008 | 8 | Strike out


TypeLib Table

The TypeLib table contains the information that needs to be placed in the registry registration of type libraries.

The TypeLib table has the following columns.

Column | Type | Key | Nullable
LibID | GUID | Y | N
Language | Integer | Y | N
Component_ | Identifier | Y | N
Version | Integer |  | Y
Description | Text |  | Y
Directory_ | Identifier |  | Y
Feature_ | Identifier |  | N
Cost | DoubleInteger |  | Y

Columns

LibID
The GUID that identifies the library.
Language
The language of the type library. This must be a non-negative number.
Component_
External key into the first column of the Component table. This column identifies the component belonging to Feature_ whose key file is the type library being registered.
Version
This is the version of the library. The major and minor versions are encoded in the two-byte integer with the minor version in the lower eight bits and the major version in the upper eight bits.
Description
A localizable description of the library.
Directory_
External key into the first column of the Directory table. This column identifies the Help path for the type library. This column is ignored during advertising.
Feature_
External key into the first column of the Feature table. This column specifies the feature that must be installed for the type library to be operational.
Cost
The cost associated with the registration of the type library in bytes. This must be a non-negative number or null.

Remarks

This table is referred to when the RegisterTypeLibraries action or the UnregisterTypeLibraries action is executed.


UIText Table

The UIText table contains the localized versions of some of the strings used in the user interface. These strings are not part of any other table. The UIText table is for strings that have no logical place in any other table.

The UIText table has the following columns.

Column | Type | Key | Nullable
Key | Identifier | Y | N
Text | Text |  | Y

Columns

Key
A unique key that identifies the particular string.
Text
The localized version of the string.

Remarks

Some controls use the UIText table as a source of strings. For information about which strings are required in this table for each particular control, see the individual controls in the User Interface Reference.


Upgrade Table

The Upgrade table contains information required during major upgrades. To fully enable the installer's upgrade capabilities, every package should have an UpgradeCode property and an Upgrade table. Each record in the Upgrade table gives a characteristic combination of upgrade code, product version, and language information used to identify a set of products affected by the upgrade. When the FindRelatedProducts action detects that an affected product is installed on the system, it appends the product code to a property specified in the ActionProperty column. The RemoveExistingProducts action and the MigrateFeatureStates action only removes or migrates products listed in the ActionProperty list.

The Upgrade table has the following columns.

Column | Type | Key | Nullable
UpgradeCode | GUID | Y | N
VersionMin | Version | Y | Y
VersionMax | Version | Y | Y
Language | Text | Y | Y
Attributes | Integer | Y | N
Remove | Formatted |  | Y
ActionProperty | Identifier |  | N

Columns

UpgradeCode
The UpgradeCode property in this column specifies the upgrade code of all products that are to be detected by the FindRelatedProducts Action.
VersionMin
Specifies the lower bound on the range of product versions to be detected by FindRelatedProducts. The format of VersionMin is the same as the ProductVersion property. A bit flag in the Attributes column specifies whether the range includes the value in VersionMin. A null VersionMin means there is no lower bound on the version. VersionMin and VersionMax must not both be null.

Note that Windows Installer uses only the first three fields of the product version. If you include a fourth field in your product version, the installer ignores the fourth field.

VersionMax
Specifies the upper boundary of the range of product versions detected by FindRelatedProducts. The format of VersionMax is the same as the ProductVersion property. A bit flag in the Attributes column specifies whether the range includes the value in VersionMax. A null VersionMax means there is no upper bound on the version. VersionMin and VersionMax must not both be null.

Note that Windows Installer uses only the first three fields of the product version. If you include a fourth field in your product version, the installer ignores the fourth field.

Language
Specifies the set of languages detected by FindRelatedProducts. Enter a list of numeric language identifiers (LANGID) separated by commas (,). A bit flag in the Attributes field specifies whether FindRelatedProducts should detect all languages exclusive of the set in Language. Enter a null value in this field to specify all languages.
Attributes
This column contains bit flags specifying attributes of the Upgrade table.
Bit Flag Name | Decimal | Hexadecimal | Attribute
msidbUpgradeAttributesMigrateFeatures | 1 | 0x001 | Migrate feature states by enabling the logic in the MigrateFeatureStates action.
msidbUpgradeAttributesOnlyDetect | 2 | 0x002 | Detect products and applications but do not install.
msidbUpgradeAttributesIgnoreRemoveFailure | 4 | 0x004 | Continue installation upon failure to remove a product or application.
msidbUpgradeAttributesVersionMinInclusive | 256 | 0x100 | The range of versions detected includes the value in VersionMin.
msidbUpgradeAttributesVersionMaxInclusive | 512 | 0x200 | The range of versions detected includes the value in VersionMax.
msidbUpgradeAttributesLanguagesExclusive | 1024 | 0x400 | Detect all languages, excluding the languages listed in the Language column.

Remove
The installer sets the REMOVE property to features specified in this column. The features to be removed can be determined at run time. The Formatted string entered in this field must evaluate to a comma-delimited list of feature names. For example: [Feature1],[Feature2],[Feature3]. No features are removed if the field contains formatted text that evaluates to an empty string. The installer sets REMOVE="ALL" only if the Remove field is empty.
ActionProperty
When the FindRelatedProducts action detects a related product installed on the system, it appends the product code to the property specified in this field. The property specified in this column must be a public property and the package author must add the property to the SecureCustomProperties Property. Each row in the ActionProperty table must have a unique ActionProperty value. After FindRelatedProducts the value of this property is a list product codes, separated by semicolons (;), detected on the system.


Verb Table

The Verb table contains command-verb information associated with file extensions that must be generated as a part of product advertisement. Each row generates a set of registry keys and values.

The Verb table has the following columns.

Column | Type | Key | Nullable
Extension_ | Text | Y | N
Verb | Text | Y | N
Sequence | Integer |  | Y
Command | Formatted |  | Y
Argument | Formatted |  | Y

Columns

Extension_
The extension associated with the table row. This column is an external key to the first column of the Extension table.
Verb
The verb for the command.
Sequence
The sequence of the commands. Only verbs for which the Sequence column is non-Null are used to prepare an ordered list for the default value of the shell key. The Verb with the lowest value in this column becomes the default verb.
Command
The localizable text displayed on the context menu.
Argument
Value for the command arguments.

Note that the resolution of properties in the Argument field is limited. A property formatted as [Property] in this field can only be resolved if the property already has the intended value when the component owning the verb is installed. For example, for the argument "[#MyDoc.doc]" to resolve to the correct value, the same process must be installing the file MyDoc.doc and the component that owns the verb.

Remarks

This table is referred to when the RegisterExtensionInfo action or the UnregisterExtensionInfo action is executed.


_Columns Table

The _Columns table is a read-only system table that contains the column catalog. It lists the columns for all the tables. You can query this table to find out if a given column exists.

The _Columns table has the following columns.

Column | Type | Key | Nullable
Table | Text | Y | N
Number | Integer | Y | N
Name | Text |  | N

Columns

Table
The name of the table that contains the column.
Number
The order of the column within the table.
Name
The name of the column.

Remarks

Because the _Columns table is a system table that cannot be modified through SQL queries, you cannot obtain the primary keys with the MsiDatabaseGetPrimaryKeys function or the PrimaryKeys property.

Only persistent columns are stored in the _Columns table. To determine if a temporary column exists one would need to create a view using a SELECT * statement against the table, then loop through all fields in a record returned by the MsiViewGetColumnInfo function with the MSICOLINFO_NAMES option.


_Storages Table

The _Storages table lists embedded OLE data storages. This is a temporary table, created only when referenced by a SQL statement.

Column | Type | Key | Nullable
Name | Text | Y | N
Data | Binary |  | Y

Columns

Name
A unique key that identifies the storage. The maximum length of Name is 31 characters.
Data
The unformatted binary data.

Remarks

To add an OLE storage to a database, create a new record in the _Storages table and enter the name of the storage into the Name column. Use MsiRecordSetStream to copy data into the Data column of this record. Finally, use MsiViewModify to insert the record into the _Storages table.

Data cannot be read from the _Storages table. However, the _Storages table can be queried to check for the existence of a specific storage. This means that it is not possible to move an OLE storage from one database to another. You must instead import the original storage file into the new database.To delete an OLE storage, fetch the record containing the binary data, set the Data column in the _Storages table to NULL, and then update the record. An alternative method is to simply delete the record using either MsiViewModify or a plain SQL query.

To rename an OLE storage, update the Name column of the record.

If a hold is placed on this table using SQL (ALTER TABLE <table> HOLD) or a column is added with HOLD, the table must be released using FREE. Storages are not written until the table has been released or committed.


_Streams Table

The _Streams table lists embedded OLE data streams. This is a temporary table, created only when referenced by a SQL statement.

Column | Type | Key | Nullable
Name | Text | Y | N
Data | Binary |  | Y

Columns

Name
A unique key that identifies the stream. The maximum length of Name is 62 characters.
Data
The unformatted binary data.

Remarks

To copy an OLE data stream (for example, an object of the Binary data type) from a file into a database, create a record in the _Streams table and enter the name of the data stream into the Name column of this record and copy the data from the file into the Data column using MsiRecordSetStream. Use MsiViewModify to insert the new record into the table.

To read a binary data stream embedded in a database, use a SQL query to find and to fetch the record containing the binary data. Use MsiRecordReadStream to read the binary data into a buffer.

To move a binary data stream from one database to another, first export the data to a file. Use a SQL query to find the data stream in the file and use MsiRecordSetStream to copy the data from the file into Data column of _Streams table of the second database. This ensures that each database has its own copy of the binary data. You cannot move binary data from one database to another simply by fetching a record with the data from the first database and inserting it into the second database.

To delete a data stream, fetch the record and set the Data column to NULL before updating the record. Another method is to remove the record from the table, deleting it using either MsiViewModify or a plain SQL query. A stream should not be fetched into a record if the stream is deleted from the table.

To rename an OLE data stream, update the 'Name' column of the record.

If a hold is placed on this table using SQL (ALTER TABLE <table> HOLD) or a column is added with HOLD, the table must be released using FREE. Streams are not written until the table has been released or committed.


_Tables Table

The _Tables table is a read-only system table that lists all the tables in the database. Query this table to find out if a table exists.

The _Tables Table has the following column.

Column | Type | Key | Nullable
Name | Text | Y | N

Column

Name
Name of one of the tables.

Remarks

Because the _Tables table is a system table that can not be modified through SQL queries, you cannot obtain the primary keys with the MsiDatabaseGetPrimaryKeys function or the PrimaryKeys property.


_TransformView Table

This is a read-only temporary table used to view transforms with the transform view mode. This table is never persisted by the installer.

To invoke the transform view mode, obtain a handle and open the reference database. See Obtaining a Database Handle. Call MsiDatabaseApplyTransform with MSITRANSFORM_ERROR_VIEWTRANSFORM. This stops the transform from being applied to the database and dumps the transform contents into the _TransformView table. The data in the table can be accessed using SQL queries. See Working with Queries.

The _TransformView table is not cleared when another transform is applied. The table reflects the cumulative effect of successive applications. To view the transforms separately you must release the table.

The _TransformView Table has the following column.

Column | Type | Key | Nullable
Table | Identifier | Y |
Column | Text | Y |
Row | Text | Y | Y
Data | Text |  |
Current | Text |  |

Column

Table
Name of an altered database table.
Column
Name of an altered table column or INSERT, DELETE, CREATE, or DROP.
Row
A list of the primary key values separated by tabs. Null primary key values are represented by a single space character. Enter Null in this field if this is a schema change.
Data
Data, name of a data stream, or a column definition.
Current
Current value from reference database, or column a number.

Remarks

The _TransformView is held in memory by a lock count, that can be released with the following SQL command.

"ALTER TABLE _TransformView FREE".

The data in the table can be accessed using SQL queries. The SQL language has two main divisions: Data Definition Language (DDL) that is used to define all the objects in an SQL database, and Data Manipulation Language (DML) that is used to select, insert, update, and delete data in the objects defined using DDL.

The Data Manipulation Language (DML) transform operations are indicated as follows. Data Manipulation Language (DML) are those statements in SQL that manipulate, as opposed to define, data.

Transform operation | SQL result
Modify data | {table} {column} {row} {data} {current value}
Insert row | {table} "INSERT" {row} NULL NULL
Delete row | {table} "DELETE" {row} NULL NULL

The Data Definition Language (DDL) transform operations are indicated as follows. Data Definition Language (DDL) are those statements in SQL that define, as opposed to manipulate, data.

Transform operation | SQL result
Add column | {table} {column} NULL {defn} {column number}
Add table | {table} "CREATE" NULL NULL NULL
Drop table | {table} "DROP" NULL NULL NULL


_Validation Table

The _Validation table is a system table that contains the column names and the column values for all of the tables in the database. It is used during the database validation process to ensure that all columns are accounted for and have the correct values. This table is not shipped with the installer database.

The _Validation table has the following columns.

Column | Type | Key | Nullable
Table | Identifier | Y | N
Column | Identifier | Y | N
Nullable | Text |  | N
MinValue | DoubleInteger |  | Y
MaxValue | DoubleInteger |  | Y
KeyTable | Identifier |  | Y
KeyColumn | Integer |  | Y
Category | Text |  | Y
Set | Text |  | Y
Description | Text |  | Y

Columns

Table
Used to identify a particular table. This key and the Column key form the primary key of the _Validation table.
Column
Used to identify a particular column of the table. This key and the Table key form the primary key of the _Validation table.
Nullable
Identifies whether or not the column may contain a Null value.

This column may have one of the following values.
String | Meaning
Y | Yes, the column may have a Null value.
N | No, the column may not have a Null value.
@ The column is a key column for the table, but it may have a Null value.

MinValue
This field applies to columns having numeric value. The field contains the minimum permissible value. This can be the minimum value for an integer or the minimum value for a date or version string.
MaxValue
This field applies to columns having numeric value. The field is the maximum permissible value. This may be the maximum value for an integer or the maximum value for a date or version string.
KeyTable
This field applies to columns that are external keys. The field identified in Column must link to the column number specified by KeyColumn in the table named in KeyTable. This can be a list of tables separated by semicolons.
KeyColumn
This field applies to table columns that are external keys. The field identified in Column must link to the column number specified by KeyColumn in the table named in KeyTable. The permissible range of the KeyColumn field is 1-32.
Category
This is the type of data contained by the database field specified by the Table and Column columns of the _Validation table. If this is a type having a numeric value, such as Integer, DoubleInteger or Time/Date, then enter null into this field and specify the value's range using the MinValue and MaxValue columns. Use the Category column to specify the non-numeric data types described in Column Data Types.
Set
This is a list of permissible values for this field separated by semicolons. This field is usually used for enums.
Description
A description of the data that is stored in the column.

Remarks

The Category field of this table only applies to string data. If the Column field refers to a column with binary data, the binary data type must be specified in the Category field. Integer data Column types ignore the Category field during validation.


User Interface

The Microsoft® Windows® Installer provides a complete user interface for installing an application or product. The user interface presents the user with the options available to configure the installation and obtains information from the user about the pending installation process.

About the User Interface describes the functionality of Windows Installer user interface. Using the User Interface describes the use of the Windows Installer internal user interface.

Reference information on Windows Installer internal dialog box and control styles and options is presented in User Interface Reference.


About the User Interface

The Microsoft® Windows® Installer contains functionality which enables installation package developers to author a graphical user interface (GUI) that is displayed to the end user during installation. This user interface can exhibit User Interface Wizard Behavior, display dialog boxes and billboards, and present interactive controls to users during the installation.

The Windows Installer internal user interface is managed and controlled through a set of database tables within Windows Installer itself. The installer provides only a small set of default dialog boxes which are intended to handle error and information messages. All custom dialog boxes must be created by the package author.

There is no specific Windows Installer API to allow a package author to create a user interface programmatically. It is possible to use the Microsoft Windows API to create a user interface programmatically; however, it is recommended that package authors use the internal user interface provided.

Installer package authors create custom dialog boxes by entering the name of their custom dialog into the "_Dialog" column of the dialog table and specifying the size, position, and other attributes using the remaining columns.

Windows Installer also implements a number of standard controls that a package author can place onto Dialog Boxes. Not all standard Microsoft Windows controls are available, and custom controls cannot be created for use with the Windows Installer user interface.

Controls are created on a specific dialog box by entering the name of the dialog box, which is the primary key to the dialog box's entry in the dialog table, into the second field of the control table and specifying the control's size, position and other attributes using the remaining columns.

Active controls must be linked to a ControlEvent in the ControlEvent table to allow user interaction with the installation. Passive controls that receive and display information must be subscribed to an appropriate ControlEvent in the EventMapping table.

For more information about ControlEvents, see ControlEvent Overview. Note that a control publishes a ControlEvent if listed in the ControlEvent table and subscribes to an event if listed in the EventMapping table.

The Windows Installer user interface display during installation is managed through the user interface sequence tables: InstallUISequence Table, and AdminUISequence Table. One of these three sequence tables is executed depending on the top level action that initiated the installation: INSTALL, ADMIN, or ADVERTISE.

For more information about implementing a user interface in Microsoft Windows Installer, please see Using the User Interface, User Interface Schema, as well as the individual topics for Dialog boxes and Controls.


User Interface Schema

See the entity relationship diagram legend for more information about this diagram.


Dialog Box Overview

The process of creating a dialog box in Windows Installer is similar to the process of creating a dialog box programmatically using a Microsoft Windows API dialog box template. While a Windows dialog box template is stored in a null terminated character string, Windows Installer stores the dialog box parameters in the Dialog table. The Dialog table contains an attributes column that is analogous to Window styles in the Microsoft Windows user interface API. However, the number of Dialog Style Bits in Windows Installer is a reduced and specialized set.

To physically create the dialog box using the Windows user interface API, DialogBox is called and passes a pointer to the template. In Windows Installer, the dialog box is created during execution of one of the three user interface sequence tables.

Windows Installer does not contain a default user interface which package authors can utilize for their packages. Windows Installer does contain a limited set of default Dialog boxes that display error and information messages, but these are displayed only if Windows Installer queries the dialog and user interface sequence tables and finds there are no custom dialogs available.

The Windows Installer Software Developer Kit contains a minimal database named Uisample.msi that contains populated user interface and execution sequence tables and a complete user interface. This database is easily customized and merged on to any package.

Some standard actions and internal Windows Installer error conditions return a specific set of user interface data and therefore require a dialog box with a specific set of controls to accommodate that data. Windows Installer checks two separate locations for the identifiers for these dialog boxes.

  1. Windows Installer contains a set of embedded dialog box names. The custom action queries the Dialog table for these reserved names.
  2. In each of the three user interface sequence tables, dialog names with a sequence number of -1,-2, or -3 are displayed in response to exit, user requested exit, and fatal error messages from Windows Installer.

A complete list of reserved primary key dialog box names is available in dialog boxes. Note that the primary key dialog box name is only reserved by the installer and there is no specific implementation of the dialog box within Windows Installer. Package authors must still populate all the fields in the database that specify the attributes and controls of these reserved dialog boxes.


Controls Overview

Windows Installer implements a number of standard controls that package authors can place onto Dialog Boxes. However, not all standard Microsoft Windows controls are available and custom controls cannot be created for use with the Windows Installer user interface.

Controls are created on dialog boxes in Windows Installer in a similar manner dialog boxes are created programmatically using the Microsoft Windows user interface API. A control is created from a template recorded in the control table. This template is slightly different in that it contains the unique name of the Dialog box on which the control appears.

In the Microsoft Windows user interface API, user interaction is accomplished by creating a callback function to handle messages posted by the control. Also, most Microsoft Windows controls receive messages, such as those sent by the SendMessage function.

Communication between the user and controls is accomplished in Windows Installer through the use of ControlEvents. However, there is a limited set of ControlEvents that are specific to each control in the limited set of controls in Windows Installer. Controls may post more than one ControlEvent and may receive more than one ControlEvent.

Controls can publish specific ControlEvents through the use of the ControlEvent table. Controls can receive ControlEvents through the use of the EventMapping table.

Windows Installer publishes ControlEvents during the execution of some actions as well, and controls subscribed to these ControlEvents in the EventMapping table receive them.


ControlEvent Overview

ControlEvents are analogous to Microsoft Windows messages in Win32-based applications. However, rather than creating a callback function to receive Windows messages and sending Windows messages with the SendMessage function, Windows Installer controls send ControlEvents specified in the ControlEvent table and receive ControlEvents specified in the EventMapping table.

To add working controls to dialog boxes, the author of the user interface first selects which ControlEvents to use and then associates these with the controls. When a user triggers a control having a ControlEvent tied to it, that ControlEvent is then published to the installer and all controls in the dialog box. If the installer subscribes to the ControlEvent, then the publication of the ControlEvent results in the installer executing an action. If any controls in the dialog box subscribe to the ControlEvent, then the publication of the ControlEvent results in a change in the attributes of these controls.

For example, consider a dialog box containing four push button controls labeled Red, Blue, Green, and All. The first three buttons publish different ControlEvents, and launch distinct actions, but all three buttons also subscribe to a ControlEvent that is published when the user clicks the All button. This ControlEvent specifies simply that the attributes of subscribing push buttons be changed to the "in" state. This UI therefore enables the user to activate all the actions published by the first three buttons by clicking the All button.

Each ControlEvent is published either by the installer or one of the controls in a dialog box. This is authored into the dialog box by listing the control together with the name of the ControlEvent in the ControlEvent table.

Although a ControlEvent is published only by the installer or a single control, the installer and controls can subscribe to multiple ControlEvents. This is authored by listing the control together with the ControlEvent in the EventMapping table. The value in the Attribute column of this table is the control attribute that is set when the subscribing control receives the ControlEvent.

If a control subscribes to a ControlEvent that is not published by the installer or a control in the same dialog box, it can result in an error.

A custom control also publishes ControlEvents that are subscribed to by the installer or other controls.

For a more information about particular ControlEvents, see the list of standard control events in User Interface Reference.


Accessibility

Authors should be aware of the tables and fields in the following list when designing their user interface to be in compliance with Active Accessibility® guidelines. The user interface of an installer package should facilitate accessibility of the application or product to all users.

  • Tooltip text is contained in the Help column of the Control table. This text is shown by screen readers for controls containing a picture.
  • The Text field of the Control table for the VolumeCostList, ListView, DirectoryList and SelectionTree controls is never displayed. Instead it can be read by screen review utilities as the description of the control. People who cannot use the visual information on the screen can interpret the information with the aid of a screen review utility. Screen review utilities (also referred to as a screen reader programs or speech access utilities) take the displayed information on the screen and direct it through alternative media, such as synthesized speech or a refreshable Braille display.
  • The Text field in Control table for certain controls, such as the VolumeCostList, ListView, DirectoryList and SelectionTree control is never displayed but is read by the screen readers as the description of the control.
  • Controls in dialog boxes should be linked using the Control_Next field of the Control table. The controls need to be authored such that they can all be reached by using the TAB key.
  • Shortcut keys should be provided for gaining access to controls directly.
  • Text color displayed in the user interface is set in the TextStyle table. If the chosen text color is too close to the background's then the text's color choice is ignored.
  • Text size and font is set in the TextStyle table. Larger font sizes should be used for packages intended for the Asian market. For example, a font size of 10 points that is legible for English text may not necessarily true for Chinese.
  • For Edit, PathEdit, ListView, ComboBox or VolumeSelectCombo controls, screen readers take accName and accKeyboardShortcut from a Text Control that must precede the control in the Control_Next sequence of the dialog box. The screen reader takes accName from the Text field of the Text control and accKeyboardShortcut from the keyboard shortcut in the Text field, if a shortcut exists.
  • Because static text cannot take the focus, a Text control that describes an Edit, PathEdit, ListView, ComboBox or VolumeSelectCombo control must be made the first control in the dialog box to ensure compatibility with screen readers.
  • For a PushButton Control that displays an icon or bitmap image, accName and accKeyboardShortcut are specified in the Help field of the Control table record, to the left of the | separator.
  • Do not put a black text control on a background that is an all white bitmap image. This text is not visible to a user who changes the Windows display to High Contrast Black.
  • Do not put a white text control on a background that is an all black bitmap image. This text is not visible to a user who changes the Windows display to High Contrast White.
  • Note that the focus on a dialog box does not tab to a RadioButtonGroup Control until one of the buttons in the group has been selected. To make the focus tab to this button group, specify one of the buttons as a default setting for the control.


User Interface Wizard Behavior

To author an simple user interface, developers of installation packages can utilize a user interface design that adheres to Interface Wizard Behavior.

The term User Interface Wizard Behavior means that each dialog box in a sequence contains a Next>> button, which the user clicks to move to the next dialog box after entering data or configuring information in the current dialog box. If the user decides to go back and change any information entered in a previous dialog box, each dialog contains a <<Previous button that the user clicks to go back. At the end of the wizard sequence, the user clicks a Finish button to begin the installation process.

The user interface described in the user interface example adheres to User Interface Wizard behavior. See An Installation Example.


User Interface Levels

The Windows Installer provides package developers the capability to author an internal user interface that has multiple levels of UI functionality. Because the internal UI must be authored, the behavior of the full UI, reduced UI, basic UI, and None levels depends on the installation package. The following table describes the functionality commonly ascribed to these levels.

UI Level | Description
Full UI | Displays both the modal and modeless dialog boxes that have been authored into the internal UI. Displays the built-in modal error-message boxes. Modal dialog boxes require user input before the installation can continue and are specified by setting the Modal Dialog Style Bit in the Attributes column of the Dialog table. A modeless dialog box does not require user input for the installation to continue. A full UI commonly exhibits User Interface Wizard Behavior.
Reduced UI | Displays the authored modeless dialog boxes. Does not display any authored modal dialog boxes. Displays built-in modal error-message boxes.
Basic UI | Displays the built-in modeless dialog boxes that show progress messages. Does not display any authored dialog boxes.
None | None means a silent installation that displays no user interface.

The level of the internal user interface can be set using MsiSetInternalUI. The installer sets the UILevel property to the current level of the user interface.

For an example of user interface authoring, see An Installation Example.


Using the User Interface

This section is concerned primarily with how developers of install packages author an installation user interface using the installer's database and internal UI. For more information about the difference between an internal and external UI see About the User Interface.

To display a dialog box sequence or billboard during the installation the name of the dialog box must be entered into the Action column of the appropriate action sequence table. The name of the dialog box must appear in the InstallUISequence or AdminUISequence table depending on whether the UI is scheduled to run under the INSTALL, ADVERTISE, or ADMIN action.

Although the installer supports the authoring of custom dialog boxes and billboards, there are also a number of reserved names for certain dialog box sequences. Because the installer uses these names when executing certain actions, these names must only be used with the types of dialog boxes for which they are reserved. A list of these reserved names, and a description of each of the special dialog box sequences, is given in Dialog Boxes.

The properties of each dialog box or billboard in the UI must be specified in the Dialog and BillBoard tables respectively. The style of each dialog box must also be specified in the Dialog table by setting the dialog's style bit flag.

Controls and text must be added to the dialog box, and these must be tied to ControlEvents, to enable the user to interact with the installation process. See Adding Controls and Text for more information on how to add controls to a dialog box.

The Windows Installer internal user interface handler can selectively show or hide dialog boxes to control the level of end-user interactivity during the installation. These levels of end-user interactivity are referred to as full, reduced, basic, and none. See User Interface Levels. for a full description of these user interface levels.

There are two methods to set the user interface level. The user interface level can be set programmatically with a call to MsiSetInternalUI, and the first parameter of MsiSetInternalUI specifies the user interface level. Package developers can also set the user interface level using the command line option "/q".

The behavior of each of the user interface levels is determined by the authoring of the .msi file by the package developer. The author of an internal UI has flexibility in how these levels behave for his package.

A full UI typically exhibits User Interface Wizard Behavior, such as each dialog box in a sequence containing a Next>> button. This form of UI is familiar to many users and is the most common simple type of UI for an author to create. The installer presents a logical sequence of dialog boxes and prompts the user to interact with controls located in each dialog box. A reduced UI typically suppresses the display of wizard behavior. A basic UI typically only displays progress messages to the user. A user interface level of None means a silent installation. The availability of these levels depends on the authoring of the installation package. The author must specify every dialog box and control in the user interface in the Dialog and Control tables.

The Windows Installer provides a unique progress bar indicator in the ProgressBar control that displays to the user an estimate of the total time remaining until the installation is complete. For more information about the progress bar, see Authoring a Progress Bar Control.

UI authors should facilitate the accessibility of their application or product to all users. To learn more about Active Accessibility® and the Windows Installer, see Accessibility.

For more information about authoring a user interface, see Adding Controls and Text, Authoring a Progress Bar Control, Authoring Disk Prompt Messages, Authoring a Conditional "Please Wait . . ." Message Box, and Previewing the User Interface.


Adding Controls and Text

Controls and text placed on dialog boxes and billboards enable the user to interact with the installation process. Add a dialog box to the user interface by including it in the Dialog table as described in Using The User Interface. You can fill dialog boxes and billboards with controls by populating the Control table and BBControl table, respectively.

The initial attributes of control can be specified in the Attributes column of the Control table. See Control Attributes.

To make control attributes dependent upon a condition, use the ControlCondition table to disable, enable, hide, or show a control according to the value of a property or conditional statement. For example, you can present a control if the operating system is Microsoft® Windows NT®/Windows® 2000 but not if it is Microsoft® Windows® 95 or later. You can also use this table to override the specification of the default control entered into the Dialog table.

To have an event change a control attribute, subscribe the control to a ControlEvent in the EventMapping table. A ControlEvent specifies an action to be taken by the installer or a change in the attributes of one or more controls in the dialog box. See ControlEvent Overview. Enter the attribute's identifier in the Attribute column and the ControlEvent's identifier in the Event column of the EventMapping table.

Some controls facilitates the collection of information from the user. For example, a check box enables the user to set the value of a property. See the CheckBox table, the ComboBox table, the ListBox table, the RadioButton table, and the ListView table.

Note that for security reasons, private properties cannot be changed by the user interacting with the user interface. If a property is to be set by the user interface it needs to be a public property and have a name in all upper case. See About Properties.

You can either make your dialog box present information to the user or write it to a log in response to installation actions by filling in the ActionText table.

Controls can have a predefined font style. Set the font style by putting the name of a style in the form {\style} at the start of the text string which is to appear in the control. Where style is a style name listed in the TextStyle field of the TextStyle table. A base text style can be assigned to any control by supplying {&style} at the start of the text string. This style is used if no other style is set by the text string. A text string may contain both style and base style specifications.

It is recommended that the DefaultUIFont property of every installation package with a UI be set in the Property table to one of the predefined styles listed in the TextStyle table. If this property is not specified, the installer uses the System font. This can cause the installer to improperly display text strings if the package's code page is different from the user's default UI code page.

For most controls, text is displayed using the character set that is specified by the code page of the database. This ensures that the correct character set is used with the information contained in the database. The exceptions to this are the Edit, DirectoryList, PathEdit, and DirectoryCombo controls which always display text using the user's default UI character set. The Text, ListBox, and ComboBox controls use the user's default UI character set if the UsersLanguage Control Attribute is set.

In some cases a control may be redrawn incorrectly when canceling out of a dialog. This has to do with the order in which the controls receive WM_PAINT messages after the Cancel dialog is removed. To fix this, try changing the order of the controls in the Control table.


Authoring a Progress Bar Control

The Windows Installer contains functionality to display a progress indicator in an action display dialog. The ProgressBar control graphically represents the installation of individual components and reports either the total time elapsed relative to time remaining or the approximate total time remaining until the installation is complete.

To determine the total time anticipated for the installation, the installer tracks the total progress ticks anticipated by each action during generation of the execution script. When script generation is complete, the progress tick total is stored and the installation begins.

Progress messages detailing the elapsed number of progress ticks are sent to the active message handler as each action in the script is executed. On each progress message, the installer broadcasts a SetProgress ControlEvent to the currently active dialog box. The user interface sequence should be authored to create the action display dialog during script execution to receive the SetProgress ControlEvent messages from the installer.

When the action display dialog receives a SetProgress ControlEvent, it checks the EventMapping table for any controls subscribing to the ControlEvent. The ProgressBar control on the action display dialog is subscribed to with the Progress control attribute specified in the attributes column. The Progress Control Attribute specifies that the ProgressBar control will be passed "ticksSoFar" and "totalTicks" values along with the SetProgress ControlEvent. The progress bar control uses this information to advance the graphical bar from left to right for an installation and from right to left for a rollback operation.

In addition, the installer broadcasts a TimeRemaining ControlEvent on each progress message. The total time remaining for the install is determined by first calculating the execution rate, which is the total number of ticks elapsed divided by the total time since the installation began. The total ticks remaining divided by the execution rate gives the approximate time remaining.

When the action display dialog receives the TimeRemaining ControlEvent, it again looks in the EventMapping table for any controls that are subscribed. In order to display the time remaining, a Text control must be subscribed to the TimeRemaining ControlEvent with the TimeRemaining control attribute specified in the attributes column.

The subscribed Text control queries the UIText table for a parameterized template string named "TimeRemaining". This string has two parameters, [1] for minutes, and [2] for seconds. The Text control converts each value to minutes and seconds, evaluates the TimeRemaining template string, and updates the text control with the new information.

If the user interface display level is set to basic or lower, the installer displays a default dialog containing a progress bar and TimeRemaining text field. For more information, see User Interface Levels.


Authoring Disk Prompt Messages

To display a message box prompting the user to insert a disk

  1. Use the authoring capabilities of the installer to set the DiskPrompt property string in the Property table. This should include the name of the product being installed and a placeholder parameter within the string for the title printed on the disk. For example, for Microsoft® Publisher the DiskPrompt property could be "Microsoft Publisher: Disk [1]", where [1] is the placeholder for the disk title.
  2. Enter the titles of each of the disks being prompted for into separate rows of the DiskPrompt column of the Media table. For example, the first and only entry into the Media table could be "1 - Install."
  3. During the InstallFiles action the value from the DiskPrompt column of the Media table is substituted for the placeholder in the string of the DiskPrompt property.
  4. The message displayed by the message box is created from a built-in template string in the Error table. This is Error 1302 and the template string is: "Please insert the disk: [2]", and the [2] represents a placeholder for the DiskPrompt property.

The example displays the following message to the user: "Please insert the disk: Microsoft Publisher: Disk 1 - Install."


Authoring a Conditional "Please Wait . . ." Message Box

The following example illustrates how to author a conditional message box that pops up and warns the user that a background task is still running whenever the user activates a displayed control prematurely.

The example also illustrates how the SpawnWaitDialog ControlEvent can in general be used to protect a control that triggers an action dependent upon the completion of a background task.

In this example, a Selection Dialog containing three push button controls labeled Install Now, Next, and Disk Cost is displayed to the user during the installation process. However, the installer also carries out a disk space costing task in the background while displaying this dialog box. The author wishes to protect these buttons from activation and wants a "Please wait" message box to pop up if the user clicks any of the buttons before the costing has completed. The author also wants this message box to contain a Cancel button and to disappear as soon as the background task is finished.

To display a dialog box asking the user to wait while background disk costing is completed

  1. Use the authoring capabilities of the installer to add a new modal dialog box, named WaitForCosting, into the Dialog table. The dialog box should display a text string that says "Please wait while disk space costing is completed."
  2. Add a single push button control to this dialog, labeled Cancel, by authoring it into the Control table.
  3. Link the Cancel push button to a control event that closes the WaitForCosting dialog box by authoring an EndDialog ControlEvent into the ControlEvent table. Set the argument of the EndDialog Control event to be Exit.
  4. Link a SpawnWaitDialog ControlEvent to the existing Install Now, Next, and Disk Cost push button controls displayed in the Selection Dialog box. Set the argument of this control event in the ControlEvent table to be the WaitForCosting dialog and set the expression in the Condition column of the table to be: CostingComplete =1.


Adding Text Stored in a Property

The example described in the section titled Authoring a Conditional "Please Wait . . . " Message Box displays a dialog box with text that reads: "Please wait while disk space costing is completed." This could be done simply by putting a Text Control on the dialog box and entering the text string into the Text column of the Control table. In this case, the information about the font style must be embedded in the string. The author must set the font and font style by prefixing the character string with {\style}. Where style is a font style identifier listed in the TextStyle column of the TextStyle table. This method of adding text is illustrated several times in An Installation Example.

An author of a user interface can also store text in a property. The following example illustrates this and shows how ControlEvents can be used to display alternative text strings.

The objective in this example is again to put up a WaitForCosting dialog box while a background task is running. The difference with the new scenario is that if the user cancels the WaitForCosting dialog box and then tries to activate the control before the background task has finished a second time, the WaitForCosting box reappears displaying an alternative message: "Disk space costing is still running. You can continue to wait or return to the main selection box to exit this sequence."

To display a "Please Wait" dialog box that displays alternative messages

  1. Begin by adding a conditional WaitForCosting dialog box to a Selection dialog box as described in Authoring a Conditional "Please Wait . . . " Message Box.
  2. Put a Text Control on the WaitForCosting dialog box by authoring a record in the Control table. Enter the identifier of the WaitForCosting dialog box into the Dialog_ column. Enter the identifier of the Text control into the Control column. Specify the type of control as Text in the Type column.
  3. Specify the Position control attribute for the text control by entering the horizontal and vertical coordinates of the control's upper left corner in the X and Y columns of the Control table. Use pixels as distance units.
  4. Specify the width and height of the text control by entering these dimensions into the Width and Height columns of the Control table. Use pixels as length units.
  5. The Property and Control_Next columns of the Control table do not affect Text controls and can be left blank in this case.
  6. Specify the control attributes for the text control that are associated with bit flags. Add the individual bit values together and enter the total into the Attributes column of the Control table. These are the Visible, Sunken, Enabled, Transparent, NoWrap, and NoPrefix control attributes. The combination of bits that display a text control on an opaque background, with wrapping text is 0, therefore enter 0 or leave the Attributes column blank.
  7. The Text column of the Control table can be left blank. The Text control displays the text string that is the value of the Text control attribute. The method for setting this attribute is described in subsequent steps of this procedure.
  8. Add a record in the Property table to define the FirstMessage message property. This property is a string containing the font style and text for the first message. Enter the name FirstMessage in the Property column. In the Value column, enter the string: "{\WaitStyle}Please wait while disk space costing is completed." Where WaitStyle is an identifier for one of the font styles listed in the TextStyle column of the TextStyle table.
  9. Add a record in the Property table to define the SecondMessage message property. This property is a string containing the font style and text for the second message. Enter the name SecondMessage in the Property column. In the Value column enter the string: "{\WaitStyle}Disk space costing is still running. You can continue to wait or return to the main selection box to exit this sequence."
  10. Add a record in the Property table to define the WaitMessage message property. This property is a string containing the font style and text for the message displayed in the WaitForCosting dialog box if the user tries to activate a pushbutton before costing is completed. Enter the name WaitMessage in the Property column. In the Value column of the Property table enter: FirstMessage.
  11. Add a SetProperty ControlEvent to the ControlEvent table that initializes Waitmessage to FirstMessage each time a new Selection Dialog box opens. Enter the identifier for the dialog box that comes just before the Selection Dialog in the dialog box sequence into the Dialog_ column. Enter the identifier for the control on this dialog box used to open the Selection Dialog box into the Control_ column. Enter [WaitMessage] into the Event column. Enter [FirstMessage] into the Argument column. Enter 1 into the Condition column and leave the Ordering column blank.
  12. Add a SetProperty ControlEvent to the ControlEvent table that sets Waitmessage to SecondMessage if the user closes the WaitForCosting dialog box before disk space costing has completed. Enter the identifier for the WaitForCosting dialog box into the Dialog_ column. Enter the identifier for the Text control into the Control_ column. Enter [WaitMessage] into the Event column. Enter [SecondMessage] into the Argument column. Enter NOT CostingComplete into the Condition column and leave the Ordering column blank.
  13. The following step links the Text control attribute to the ControlEvent that spawns the WaitForCosting dialog box. This causes the installer to pass the value of the WaitMessage property to the Text control attribute each time the user opens a WaitForCosting dialog box.
  14. Subscribe the Text control attribute of the Text control to the SpawnWaitDialog ControlEvent that opens the WaitForCosting dialog box by adding a record to the EventMapping table. Enter the identifier for the WaitForCosting dialog box in the Dialog_ column. Enter the identifier for the Text control into the Control_ column. Enter SpawnWaitDialog into the Event column. Enter Text, the identifier for the Text control attribute, into the Attribute column of the EventMapping table.


Previewing the User Interface

The installer stores all information about the user interface in the tables of the installation database. To facilitate the design of the user interface the installer also provides a preview mode for viewing this information. The following procedure describes how to enable the user interface preview mode and display the current appearance of dialog boxes and billboards.

To view the user interface in the preview mode

  1. Enable the preview mode by calling the MsiEnableUIPreview function.
  2. Display the particular dialog boxes by calling the MsiPreviewDialog function.
  3. Display particular billboards by calling the MsiPreviewBillboard function.


Monitoring an Installation Using MsiSetExternalUI

Package authors can monitor internal Windows Installer messages through the creation of an executable application that contains both a callback handler to receive the messages and functionality to initiate an installation.

The callback handler conforms to the INSTALLUI_HANDLER prototype, and a pointer to this callback handler is passed to MsiSetExternalUI. Once the installation has been initiated by a call to MsiInstallProduct, installation messages are trapped by the callback handler and the package author can selectively display or ignore any or all of these messages.

For more information, see Handling Progress Messages Using MsiSetExternalUI, Returning Values from an External User Interface Handler, and Parsing Windows Installer Messages.


Handling Progress Messages Using MsiSetExternalUI

The following sample demonstrates how to code a simple callback handler to receive Windows Installer progress messages during an installation.

// Globals
//
//    common data information fields
//    int g_rgiField[3]; //array of fields to handle INSTALLOGMODE_COMMONDATA data
//    WORD g_wLANGID = LANG_NEUTRAL; // initialize to neutral language
//
//    progress information fields
//    int iField[4]; //array of record fields to handle INSTALLOGMODE_PROGRESS data
//    int  g_iProgressTotal = 0; // total ticks on progress bar
//    int  g_iProgress = 0;      // amount of progress
//    BOOL g_bForwardProgress = TRUE; //TRUE if the progress bar control should be incremented in a forward direction
//    BOOL g_bScriptInProgress = FALSE;
//    BOOL g_bEnableActionData; //TRUE if INSTALLOGMODE_ACTIONDATA messages are sending progress information

// In the following snippet, note that the internal user
// interface level is set to INSTALLLEVEL_NONE. If the internal
// user interface level is set to anything other than
// INSTALLUILEVEL_NONE, the user interface level is
// INSTALLUILEVEL_BASIC by default and the installer only
// displays an initial dialog. If the authored wizard
// sequence of the package is to be displayed, the user
// interface level should be set to INSTALLUILEVEL_FULL.
// If the external user interface handler is to have full
// control of the installation user interface, the user
// interface level must be set to INSTALLUILEVEL_NONE.

MsiSetInternalUI(INSTALLUILEVEL_NONE,NULL);

MsiSetExternalUI (TestMyBasicUIHandler,
    INSTALLLOGMODE_PROGRESS|INSTALLLOGMODE_FATALEXIT|INSTALLLOGMODE_ERROR
                        |INSTALLLOGMODE_WARNING|INSTALLLOGMODE_USER|INSTALLLOGMODE_INFO
                        |INSTALLLOGMODE_RESOLVESOURCE|INSTALLLOGMODE_OUTOFDISKSPACE
                        |INSTALLLOGMODE_ACTIONSTART|INSTALLLOGMODE_ACTIONDATA
                        |INSTALLLOGMODE_COMMONDATA|INSTALLLOGMODE_PROGRESS|INSTALLLOGMODE_INITIALIZE
                        |INSTALLLOGMODE_TERMINATE|INSTALLLOGMODE_SHOWDIALOG,
                        TEXT("TEST"));

MsiInstallProduct(/*full path to package*/,NULL);

//
//  FUNCTION: TestMyBasicUIHandler()
//
//  PURPOSE: Demonstrates usage of an external user interface handler for MSI
//
//  COMMENTS:
//
int _stdcall TestMyBasicUIHandler(LPVOID pvContext, UINT iMessageType, LPCSTR szMessage)
{
    if(pvContext != NULL);
        /* Any operations that are performed using the application context occur here.*/

    INSTALLMESSAGE mt;
    UINT uiFlags;

    mt = (INSTALLMESSAGE)(0xFF000000&(UINT)iMessageType);
    uiFlags = 0x00FFFFFF&iMessageType;

    switch (mt)
    {
        //Premature termination
    case INSTALLMESSAGE_FATALEXIT:
        //return '0' to indicate the external UI handler has not taken any action
        return 0;

    case INSTALLMESSAGE_ERROR:
        {
            /* Get error message here and display it*/
            // language and caption can be obtained from common data msg
            MessageBeep(uiFlags & MB_ICONMASK);
            return MessageBoxEx(0, szMessage, TEXT("Error"), uiFlags, g_wLANGID);
        }
    case INSTALLMESSAGE_WARNING:
        /* Get warning message here and display it */
        MessageBox(0, szMessage, TEXT("Warning"), uiFlags);
        return IDOK;

    case INSTALLMESSAGE_USER:
        /* Get user message here */
        // parse uiFlags to get Message Box Styles Flag and return appopriate value, IDOK, IDYES, etc.
        return IDOK;

    case INSTALLMESSAGE_INFO:
        return IDOK;

    case INSTALLMESSAGE_FILESINUSE:
        /* Display FilesInUse dialog */
        // we'll let Windows Installer handle this one
        return 0;

    case INSTALLMESSAGE_RESOLVESOURCE:
        /* ALWAYS return 0 for ResolveSource */
        return 0;

    case INSTALLMESSAGE_OUTOFDISKSPACE:
        /* Get user message here */
        return IDOK;

    case INSTALLMESSAGE_ACTIONSTART:
        return IDOK;

    case INSTALLMESSAGE_ACTIONDATA:
        // only act if progress total has been initialized
        if (0 == g_iProgressTotal)
            return IDOK;
        SetDlgItemText(/*handle to your dialog*/,/*identifier of your actiontext control*/, szMessage);
        if(g_bEnableActionData)
        {
            SendMessage(/*handle to your progress control*/,PBM_STEPIT,0,0);
        }
        return IDOK;

    case INSTALLMESSAGE_PROGRESS:
        {
            if(ParseProgressString(const_cast<LPSTR>(szMessage)))
            {
                // all fields off by 1 due to c array notation
                switch(iField[0])
                {
                case 0: // reset progress bar
                    {
                        //field 1 = 0, field 2 = total number of ticks, field 3 = direction, field 4 = in progress

                        /* get total number of ticks in progress bar */
                        g_iProgressTotal = iField[1];

                        /* determine direction */
                        if (iField[2] == 0)
                            g_bForwardProgress = TRUE;
                        else // iField[2] == 1
                            g_bForwardProgress = FALSE;

                        /* get current position of progress bar, depends on direction */
                        // if Forward direction, current position is 0
                        // if Backward direction, current position is Total # ticks
                        g_iProgress = g_bForwardProgress ? 0 : g_iProgressTotal;
                        SendMessage(/*handle to your progress control*/,PBM_SETRANGE,0,MAKELPARAM(0,g_iProgressTotal));
                        // if g_bScriptInProgress, finish progress bar, else reset (and set up according to direction)
                        SendMessage(/*handle to your progress control*/,PBM_SETPOS,g_bScriptInProgress ? g_iProgressTotal : g_iProgress, 0);

                        /* determine new state */
                        // if new state = 1 (script in progress), could send a "Please wait..." msg
                        g_bScriptInProgress = (iField[3] == 1) ? TRUE : FALSE;
                        break;
                    }
                case 1:
                    {
                        //field 1 = 1, field 2 will contain the number of ticks to increment the bar
                        //ignore if field 3 is zero
                        if(iField[3])
                        {
                            // movement direction determined by g_bForwardProgress set by reset progress msg
                            SendMessage(/*handle to your progress control*/,PBM_SETSTEP,g_bForwardProgress ? iField[1] : -1*iField[1],0);
                            g_bEnableActionData = TRUE;
                        }
                        else
                        {
                            g_bEnableActionData = FALSE;
                        }
                        break;
                    }
                case 2:
                    {
                        // only act if progress total has been initialized
                        if (0 == g_iProgressTotal)
                            break;
                        //field 1 = 2,field 2 will contain the number of ticks the bar has moved
                        // movement direction determined by g_bForwardProgress set by reset progress msg
                        SendMessage(/*handle to your progress control*/,PBM_DELTAPOS,g_bForwardProgress ? iField[1] : -1*iField[1],0);
                        break;
                    }
                case 3: // fall through (we don't care to handle it -- total tick count adjustment)
                default:
                    {
                        break;
                    }
                }
            }
            if(g_bCancelInstall == TRUE)
            {
                return IDCANCEL;
            }
            else
                return IDOK;
        }

    case INSTALLMESSAGE_COMMONDATA:
        {
            if (ParseCommonDataString(const_cast<LPSTR>(szMessage)))
            {
                // all fields off by 1 due to c array notation
                switch (g_rgiField[0])
                {
                case 0:
                    // field 1 = 0, field 2 = LANGID, field 3 = CodePage
                    g_wLANGID = g_rgiField[1];
                    break;
                case 1:
                    // field 1 = 1, field 2 = CAPTION
                    /* you could use this as the caption for MessageBoxes */
                    break;
                case 2:
                    // field 1 = 2, field 2 = 0 (hide cancel button) OR 1 (show cancel button)
                    ShowWindow(/*handle to cancel button control on the progress indicator dialog box*/, g_rgiField[1] == 0 ? SW_HIDE : SW_SHOW);
                    break;
                default:
                    break;
                }
            }
            return IDOK;
        }

    // this message is received prior to internal UI initialization, no string data
    case INSTALLMESSAGE_INITIALIZE:
        return IDOK;

    // Sent after UI termination, no string data
    case INSTALLMESSAGE_TERMINATE:
        return IDOK;

    //Sent prior to display of authored dialog or wizard
    case INSTALLMESSAGE_SHOWDIALOG:
        return IDOK;

    default:
        return 0;
    }
}

//
//  FUNCTION: ParseCommonDataString(LPSTR sz)
//
//  PURPOSE:  Parses the common data message sent to the INSTALLUI_HANDLER callback
//
//  COMMENTS: Ignores the 3rd field and the caption common data message. Assumes correct syntax.
//
BOOL ParseCommonDataString(LPSTR sz)
{
    char *pch = sz;
    if (0 == *pch)
        return FALSE; // no msg

    while (*pch != 0)
    {
        char chField = *pch++;
        pch++; // for ':'
        pch++; // for sp
        switch (chField)
        {
        case '1': // field 1
            {
                // common data message type
                g_rgiField[0] = *pch++ - '0';
                if (g_rgiField[0] == 1)
                    return FALSE; // we are ignoring caption messages
                break;
            }
        case '2': // field 2
            {
                // because we are ignoring caption msg, these are all ints
                g_rgiField[1] = FGetInteger(pch);
                return TRUE; // done processing
            }
        default: // unknown field
            {
                return FALSE;
            }
        }
        pch++; // for space (' ') between fields
    }

    return TRUE;
}

//
//  FUNCTION: FGetInteger(char*& pch)
//
//  PURPOSE:  Converts the string (from current pos. to next whitespace or '\0')
//            to an integer.
//
//  COMMENTS: Assumes correct syntax.  Ptr is updated to new position at whitespace
//            or null terminator.
//
int FGetInteger(char*& rpch)
{
    char* pchPrev = rpch;
    while (*rpch && *rpch != ' ')
        rpch++;
    *rpch = '\0';
    int i = atoi(pchPrev);
    return i;
}

//
//  FUNCTION: ParseProgressString(LPSTR sz)
//
//  PURPOSE:  Parses the progress data message sent to the INSTALLUI_HANDLER callback
//
//  COMMENTS: Assumes correct syntax.
//
BOOL ParseProgressString(LPSTR sz)
{
    char *pch = sz;
    if (0 == *pch)
        return FALSE; // no msg

    while (*pch != 0)
    {
        char chField = *pch++;
        pch++; // for ':'
        pch++; // for sp
        switch (chField)
        {
        case '1': // field 1
            {
                // progress message type
                if (0 == isdigit(*pch))
                    return FALSE; // blank record
                iField[0] = *pch++ - '0';
                break;
            }
        case '2': // field 2
            {
                iField[1] = FGetInteger(pch);
                if (iField[0] == 2 || iField[0] == 3)
                    return TRUE; // done processing
                break;
            }
        case '3': // field 3
            {
                iField[2] = FGetInteger(pch);
                if (iField[0] == 1)
                    return TRUE; // done processing
                break;
            }
        case '4': // field 4
            {
                iField[3] = FGetInteger(pch);
                return TRUE; // done processing
            }
        default: // unknown field
            {
                return FALSE;
            }
        }
        pch++; // for space (' ') between fields
    }

    return TRUE;
}


Returning Values from an External User Interface Handler

An external user interface handler can return any number of values to Windows Installer depending on the button type provided in the message type parameter Windows Installer passes to the handler.

The external user interface handler can return the values -1 and 0 at any time because these are not related to the button types. A return value of -1 indicates that an internal error occurred in the external user interface handler. A return value of 0 indicates that the external user interface handler has not handled the Windows Installer message and the installer must handle the message instead.

For messages that do not include a button type, such as INSTALLMESSAGE_ACTIONDATA and INSTALLMESSAGE_PROGRESS, returning IDCANCEL cancels the installation. Returning IDOK notifies the installer that the message was handled by the external user interface handler.

The remaining return values, as described below, are directly related to the button types that are included with the message type.

External User Interface Return Value | Meaning
IDOK | OK button was pressed by the user. The message information was understood.
IDCANCEL | CANCEL button was pressed. Cancel the installation.
IDABORT | ABORT button was pressed. Abort the installation.
IDRETRY | RETRY button was pressed. Try action again.
IDIGNORE | IGNORE button was pressed. Ignore the error and continue.
IDYES | YES button was pressed. The affirmative response, continue with current sequence of events..
IDNO | NO button was pressed. The negative response, do not continue with current sequence of events.

For example, if the external user interface handler is sent a message with the MB_ABORTRETRYIGNORE message box styles flag, the external UI handler can return one of the following values:

  • -1 (error in external UI handler)
  • 0 (no action taken in external UI handler, let Windows Installer handle it)
  • IDABORT (abort button pressed)
  • IDRETRY (retry button pressed)
  • IDIGNORE (ignore button pressed)
int   WINAPI  MyMessageHandler(LPVOID pvContext, UINT iMessageType, LPCTSTR szMessage)
{
    INSTALLMESSAGE mt = (INSTALLMESSAGE)(0xFF000000&(UINT)iMessageType);
    UINT uiButtons_Icons = (0x00FFFFFF&(UINT)iMessageType);
    switch (mt)
    {
        case INSTALLMESSAGE_ERROR:
            // Since the data passed to the external UI handler
            // consists of the message and the message box styles,
            // call the Win32 API MessageBox with the provided
            // string.
            return MessageBox(NULL, szMessage, TEXT("ERROR"),  uiButtons_Icons);
        case INSTALLMESSAGE_FATALEXIT:
            return MessageBox(NULL, szMessage, TEXT("FATALEXIT"),  uiButtons_Icons);
        default:
            return 0; // do not handle the message, let Windows Installer handle it
    }
}


Parsing Windows Installer Messages

When MsiSetExternalUI is called, the second parameter contains a list of installer messages that the external user interface handler will process. In many cases, the external UI handler filters for certain messages but will not handle them. Using this method, an external user interface handler can monitor the installation without affecting the installation in any way.

Windows Installer messages contain a string that in certain cases must be parsed before it is useful.

The following list of Windows Installer messages contain simple string messages that can be displayed directly using a dialog box. As discussed in Returning Values from an External User Interface Handler, Windows Installer messages also contain a list of buttons and icons that should be displayed by the dialog box. The MB_ICONMASK, MB_DEFMASK, and MB_TYPEMASK values can be used to determine the icons and default buttons.

Windows installer message | Meaning of string data
INSTALLMESSAGE_FATALEXIT | Premature termination of installation has occurred. No processing of string required, it can be displayed directly.
INSTALLMESSAGE_ERROR | Formatted error message. No processing of string required, it can be displayed directly.
INSTALLMESSAGE_WARNING | Formatted warning message. No processing of string required, it can be displayed directly.
INSTALLMESSAGE_INFO | Formatted log message. No processing of string required, it can be displayed directly.
INSTALLMESSAGE_USER | Formatted user message. No processing of string required, it can be displayed directly.
INSTALLMESSAGE_OUTOFDISKSPACE | Formatted message indicating an out of disk space condition. No processing of string required, it can be displayed directly

INSTALLMESSAGE_RESOLVESOURCE
An external user interface handler may filter the INSTALLMESSAGE_RESOLVESOURCE message, but it should not act upon it. Instead, the external user interface handler must return 0 and allow Windows Installer to handle the message.
INSTALLMESSAGE_FILESINUSE
An external user interface should display a FilesInUse dialog in response to the INSTALLMESSAGE_FILESINUSE message.
INSTALLMESSAGE_ACTIONSTART
The format of this string is Action [1]: [2]. [3] where:

[1] is the TIME the action started

[2] is the name of the action (from the particular Sequence table)

[3] is the description of the action (as described in the Description column of the ActionText table or established via a MsiProcessMessage call)

For example:

Action 16:31:56: RemoveRegistryValues. Removing system registry values

INSTALLMESSAGE_ACTIONDATA
The format follows the ActionTemplate provided in the template column of the ActionText table for the particular action or as established by a MsiProcessMessage call. After an ACTIONSTART message, any number of ACTIONDATA messages, from 0 and up, can be received.
INSTALLMESSAGE_COMMONDATA
There are three types of CommonData messages: Language, Caption, and CancelShow.

CommonData messages can have up to three fields. A field is designated by a number followed by a colon. Field 1 is "1:<data>". Field 2 is "2:<data>". Not all fields are required to be present and at times a CommonData message may be a NULL or blank ("") string.

Language
For example: 1:0 2:1033 3:1252
Field 1: 0 // The '0' in this field indicates that common data message is of type Language.

Field 2: LANGID // In the above example, the LANGID is 1033 for English.

Field 3: CodePage // In the above example, the CodePage is 1252, a US ANSI codepage.

Caption
For example: 1:1 2:TestDb 3:NULL
Field 1: 1 // The '1' in this field indicates that common data message is of type Caption.

Field 2: TestDb // In the above example, the Caption is TestDb. The external UI handler might use this string as the Caption/Title for Dialogs and MessageBoxes.

Field 3: NULL // Field 3 may or may not always be a part of the string.

CancelShow
For example: 1:2 2:1
Field 1: 2 // The '2' in this field indicates that common data message is of type CancelShow.

Field 2: 1 // A value of '0' indicates the cancel button should be hidden. A value of '1' indicates the cancel button should be visible. In the above example, this value literally means "Show/Enable the cancel button".

INSTALLMESSAGE_PROGRESS
There are four types of Progress messages: Reset, ActionInfo, ProgressReport, and ProgressAddition. Depending upon the previous execution state, the progress bar may either need to be reset or completed. Any external handler code should not act upon any initial progress messages until the first "Reset" progress message has been received and established the total number of ticks for the progress bar.
Reset
Field 1: 0 // A '0' indicates that the progress bar should be reset

Field 2: // Contains the expected total number of ticks in progress bar.

Field 3: // Indicates direction of progress bar movement. '0' = forward, '1' = backward.

Field 4: // Indicates execution state. '0' = in progress, time remaining calculation can be made, '1' = begin of script, a "Please wait ..." message can be displayed.

ActionInfo
Field 1: 1 // A '1' indicates the string contains action information.

Field 2: // Contains the number of ticks the progress bar moves for each ActionData message received.

Field 3: // If this field is '0', field 2 should be ignored. If this field is '1', increment the progress bar by the number of ticks specified in field 2 for each ActionData message received.

Field 4: // Unused.

ProgressReport
Field 1: 2 // A '2' indicates the string contains progress information.

Field 2: // Contains the number of ticks the progress bar has moved.

Field 3: // Unused.

Field 4: // Unused.

ProgressAddition
Field 1: 3 // A '3' indicates that an action can add ticks to the progress bar.

Field 2: // Contains the number of ticks to add to total expected progress ticks.

Field 3: // Unused.

Field 4: //Unused.

The following Windows Installer messages refer to the Windows Installer user interface and provide a way for an external user interface handler to monitor a Windows Installer sequence. The external user handler is notified by the installer at the start of user interface sequence, as each dialog is presented, and at the end of user interface sequence.

INSTALLMESSAGE_TERMINATE
The string is a NULL string. No processing is required. This message indicates the end of the user interface sequence.
INSTALLMESSAGE_INITIALIZE
The string is a NULL string. No processing is required. This message indicates that the user interface sequence has started.
INSTALLMESSAGE_SHOWDIALOG
The string contains the name of the current dialog. No processing is required.


Sending Messages to Windows Installer Using MsiProcessMessage

The messages sent using MsiProcessMessage are the same messages that are received by the INSTALLUI_HANDLER callback function if MsiSetExternalUI was called. Otherwise, Windows Installer handles the messages. For details, see Parsing Windows Installer Messages.

For example, to send a INSTALLMESSAGE_ERROR message with the MB_ICONWARNING icon and the MB_ABORTRETRYCANCEL buttons:

MsiProcessMessage(hInstall, INSTALLMESSAGE(INSTALLMESSAGE_ERROR|MB_ABORTRETRYCANCEL|MB_ICONWARNING), hRec)

Where hInstall is the handle to the installation, provided to a custom action or the hProduct handle from MsiOpenProduct or MsiOpenPackage, and hRec is the record containing the error information to format. For information on how formatting is performed, see MsiFormatRecord.

By default, if an INSTALLMESSAGE_ERROR or INSTALLMESSAGE_FATALEXIT message is sent without specifying button type or icon types, MB_OK, no icon, and MB_DEFBUTTON1 are used.

Windows Installer does not label the ABORT button with the "Abort" string when displaying a MessageBox with the MB_ABORTRETRYIGNORE button specification, instead it labels the button with the "Cancel" string. All error messages refrain from using the word "Abort" and instead use the word "Cancel".

The hRecord parameter of the MsiProcessMessage function depends upon the message type sent to the MsiProcessMessage. The following list details the requirements of the record in relation to the message type:

INSTALLMESSAGE_FATALEXIT
INSTALLMESSAGE_INFO
INSTALLMESSAGE_OUTOFDISKSPACE

Field | Description
0 | Template for the formatting of the resultant string. See MsiFormatRecord for more information. The fields of the record are referenced using [1] for field 1, [2] for field 2, etc.
1 through n | All subsequent fields are directly related to the fields referenced by the template in field 0.

If field 0 is NULL, the string received by the user interface handler is formatted as: 1: [data from field 1] 2: [data from field 2] meaning that for each field of the record, the string contains the field number followed by the data stored in the field.

Information messages from MsiProcessMessage are logged when MsiEnableLog, the '/l' command line option, or the logging policy specify 'i' or INSTALLLOGMODE_INFO.

INSTALLMESSAGE_ERROR
INSTALLMESSAGE_WARNING
INSTALLMESSAGE_USER

To use a message from the Error table.

Field | Description
0 | Must be NULL.
1 | Message number in the Error table.
2 through n | Related to the specified message in the Error table.

For example.

Field | Type | Data
0 | string | NULL
1 | int | 1304
2 | string | Myfile.txt

The resulting message received from the UI handler is:

Error 1304. Error writing to file: Myfile.txt. Verify that you have access to that directory.

If field 0 is not NULL, the message from the error table is overridden. Instead, the field 0 template determines the format of the message.

The message may also specify the buttons, including the default button, and the icon for use with the message as mentioned above. The button and icon types are listed in INSTALLUI_HANDLER.

INSTALLMESSAGE_COMMONDATA

This message is sent to enable or disable the Cancel button in a progress dialog box.

Field | Description
0 | Unused.
1 | 2 refers to the Cancel button.
2 | A value of 1 indicates the Cancel button should be visible. A value of 0 indicates the Cancel button should be invisible.

For example, to disable or hide the Cancel button, the record would appear as follows.

Field | Type | Data
0 | string | NULL
1 | int | 2
2 | int | 0

INSTALLMESSAGE_ACTIONSTART
INSTALLMESSAGE_ACTIONDATA

The INSTALLMESSAGE_ACTIONSTART record determines the format of the ActionData record.

Field | Description
0 | NULL
1 | Action name.
2 | Action description.
3 | Action template. This is used for the ActionData whose message is being formatted according to this template.

Do not reference field 0 in the Action template message.

The INSTALLMESSAGE_ACTIONDATA record is formatted as follows.

Field | Description
0 | NULL
1 through n | Dependent upon field 3 of the corresponding INSTALLMESSAGE_ACTIONSTART message or template specified in ActionText table.

For example, the INSTALLMESSAGE_ACTIONSTART record.

Field | Type | Data
0 | string | NULL
1 | string | MyAction
2 | string | This is the description of "MyAction"
3 | string | MyAction template: field1 data is [1]. field 2 data is [2].

The template for INSTALLMESSAGE_ACTIONSTART (field 3) references fields 1 and 2, the INSTALLMESSAGE_ACTIONDATA record should have 2 fields containing the warranted data. The fields could be either string or integer fields.

INSTALLMESSAGE_ACTIONDATA record.

Field | Type | Data
0 | string | NULL
1 | int | 2
2 | string | ActionData for MyAction

INSTALLMESSAGE_FILESINUSE

The FILESINUSE record is a variable length record. Field 0 of the record may be NULL or contain optional static text for display in the ListBox control of the FilesInUse dialog. The first field is the name of the file in use. The second record field is the title of the window of the process holding the file in use.

Field | Description
0 | This field can be NULL. For an installation using a basic UI, this field may specify static text to be displayed by the built-in FilesInUse dialog. For an installation using a full UI, this field has no effect because the text is specified by the authoring of the custom FilesInUse dialog.
1 | Name of the file in use.
2 | Title of window for the process holding the file in use.

For example, to send a FilesInUse message showing two files in use, red.exe and blue.exe, the record has 4 fields plus the 0 field. The format of the record would be:

Field | Description
0 | NULL
1 | red.exe
2 | Red Window Title
3 | blue.exe
4 | Blue Window Title

INSTALLMESSAGE_RESOLVESOURCE

The INSTALLMESSAGE_RESOLVESOURCE record has 7 fields. For INSTALLMESSAGE_RESOLVESOURCE to work correctly, an external user interface handler may not handle the INSTALLMESSAGE_RESOLVESOURCE message. Windows Installer must handle the INSTALLMESSAGE_RESOLVESOURCE message. That is, the external user interface handler returns 0 to indicate "no action taken" when filtering the INSTALLMESSAGE_RESOLVESOURCE message. The best practice is to avoid sending a RESOLVESOURCE message.

Field | Description
0 | NULL
1 | NULL
2 | Package name.
3 | Product code.
4 | Relative path if known, can be NULL.
5 | 0
6 | Whether to validate the package code. A value of '1' indicates the package code should be validated. A value of '0' indicates the package should not be validated.
7 | Required disk from media table. A value of '0' indicates that any disk is acceptable.


User Interface Reference

The material in this section is intended for developers who are writing their own setup programs and are using the internal user interface of the Microsoft® Windows® Installer database. For general information about the installer, see About Windows Installer.

For more information about how to author a user interface, see Using the User Interface.

Dialog Boxes
Dialog Style Bits
Controls
Control Attributes
Control Events


Dialog Boxes

Dialog boxes are specified in the Dialog column of the Dialog table. For more information on adding a dialog box or billboard to a user interface, see Using the User Interface.

Reserved Dialog Box Names

The following dialog box names are reserved by Windows Installer and should not be used for any user-authored custom dialog boxes. The installer requires that these dialog boxes be listed in the Dialog table using the following reserved names. Each dialog box and name can only be listed once. Developers must author these dialog boxes into the user interface. For information about how to preview dialog boxes, see Importing the User Interface.

Dialog box name | Brief description of dialog box
FilesInUse Dialog | Alerts user to processes overwriting or deleting files.
FirstRun Dialog | Collects user name, company name, and product ID.

Required Dialog Boxes

During the installation, certain events cause Windows Installer to check the user interface sequence tables in the package and display the specified dialog box. For example, in the case of a fatal error, Windows Installer displays the dialog box that is listed with a sequence number of -3 in the user interface sequence table regardless of what that dialog box is named in the dialog table. The following table lists the specific events and their corresponding sequence number in the user interface sequence table:

Type of Event | User interface sequence table sequence number | Description of dialog box
Fatal error | -3 | The installation was terminated by a fatal error.
User exit | -2 | The installation was terminated at the user's request.
Exit | -1 | The installation completed successfully.

In addition, the package author must create a generic dialog box to display Windows Installer error messages. This dialog box can be named anything, but this name must be specified in the ErrorDialog property.

Typical Dialog Boxes

The following dialog boxes are optional and are commonly included in the authored user interface of an installation package. These dialogs are typical of most user interface wizards for installing files. These dialog boxes can have any name in the dialog table. The names shown are only recommended for clarity and can be modified as necessary. For example, two different custom LicenseAgreement dialogs can be used in the package and distinguished in the Dialog table by the names ProfessionalLicenseAgreement and LimitedLicenseAgreement.

Dialog box type | Brief description of dialog box
DiskCost dialog box | Indicates insufficient disk space for the installation.
Browse dialog box | Enables user to select a directory.
Cancel dialog box | Confirms a request to terminate the installation.
License agreement dialog box | Modal box displaying the license agreement.
Selection dialog box | Modal box enabling the user to select items.


Browse Dialog

A Browse dialog box enables the user to select a directory. The directory does not have to exist and may be created by using this control.

This type of dialog box commonly contains the following three controls. These controls are connected to the same property. That property is the path being selected.

  • A PathEdit control to select the tail section of the path. This control cannot lose focus if the entered tail is not valid on the present volume.
  • A DirectoryCombo control to show the presently selected path that is displayed by the PathEdit control. This control does not show the last segment of the path.
  • A DirectoryList control to show the folders below the directory currently displayed by the DirectoryCombo. This can also show a folder that is not yet created.

A Browse dialog box also usually contains a DirectoryCombo control that specifies the volume types to display. It is common for all volume types to be displayed on a Browse dialog box.

Browse dialog boxes commonly contain three PushButton controls. These buttons are linked to their respective ControlEvents in ControlEvent Table. These buttons are used for activating the following control options.

Control option | ControlEvent
Up One Level | DirectoryListUp
New Folder | DirectoryListNew
Open | DirectoryListOpen

For the New Folder option to work with a non-default folder name, the new folder's path must be specified in the UIText Table. The path string should use the "short file name|long file name" form for the file name. For example, use a file name such as "MyProd~1|My Fabulous Product". See the Filename column data type for more information about the file name format. If the path is not present in the UIText table, or if it is set to an invalid value, then it is set to a value of "Fldr|New Folder" by default. The New Folder button can be omitted if the dialog box only need to search for existing folders.


Cancel Dialog

A Cancel dialog box confirms that the user wants to terminate the installation. This is a modal dialog box.

This type of dialog box commonly contains a Text control and two PushButtons.

The two buttons give the user the choice of either returning to the last dialog box or confirming the termination of the installation.

The EndDialog control event is linked to these two buttons in the ControlEvent Table. The Return parameter of the EndDialog control event is linked to one of the buttons and causes the Cancel dialog box to be terminated and the focus to return to the previous dialog box. The Exit parameter is linked to the other button and causes the user interface to return control to the installer with the appropriate code indicating that the user wants to exit. The installer then shuts down and displays the UserExit Dialog.


DiskCost Dialog

A DiskCostdialog dialog box commonly appears when the OutOfDiskSpace property is set. This indicates that there is not enough disk space for the selected installation.

This dialog box may also be activated from the Selection Dialog to give the user an overview of the disk space needed for the installation.

A DiskCost dialog box is a modal dialog box. It commonly contains a PushButton that returns the user to the previous dialog box and a VolumeCostList control.


Error Dialog

An Error dialog box is a modal dialog box that displays an error message. More than one error dialog box can exist in each installation.

An ErrorDialog property needs to be set that specifies which dialog box is to be used as an error dialog box. If this property is not set or does not point to a valid error dialog box, then the error messages will not displayed. In this case the error is only logged with a warning about the missing error dialog box.

An error dialog box must have the Error Dialog style bit set. The dialog box must have a Text control named ErrorText. The record for the error dialog box in the Dialog table must have the ErrorTest control entered into the Control_First field.

The dialog box must contain seven PushButtons. All of these buttons specify the EndDialog control event in the ControlEvent Table. Each button specifies one of the following attributes: ErrorAbort, ErrorCancel, ErrorIgnore, ErrorNo, ErrorOk, ErrorRetry, ErrorYes.

Note The focus of these controls should not be linked through the use of the Control_Next column in the Control table.

These buttons should be placed in approximately the same position in the dialog box because when the dialog box is created only a subset of these seven buttons is created, depending on the message. The X coordinate of the buttons is modified so the buttons that are displayed are evenly spaced. The Y coordinate, height, and width of the buttons are unchanged. Because the buttons are arranged horizontally, no other control can be placed in the same horizontal region of the dialog box.

The error message consists of three parts. The first part is required and is the text of the error message.

The second part is a list of letters, enclosed in curly braces, that specify which buttons to create. The letters are the first letters of the words abort, cancel, ignore, no, OK, retry, and yes. All the letters must be lowercase except the one that designates the default button. If this list of codes is missing or empty, it is assumed to be {O} and the OK button becomes the default. Note that it is not possible for the package author to specify which buttons are created and displayed on the ErrorDialog box in response to specific error conditions. Windows Installer determines which buttons are displayed based on the error condition encountered. The error text contained in the Error table should make reference to the buttons Windows Installer displays.

The third part of the error message is optional. If present, this string is used as the title for the dialog box and replaces the title entered in the Dialog Table. If this string is present the second part must also be present.

For an error dialog box, the Control_Default and Control_Cancel fields in the Dialog Table are ignored. The Control_First field for an error dialog box must specify the ErrorText control.

If an Icon Control named ErrorIcon is included on this dialog, the following standard Windows icons are displayed:

  • IDI_ERROR in response to imtFatalExit messages.
  • IDI_WARNING in response to imtError and imtWarning messages.
  • IDI_INFORMATION in response to imtOutOfDiskSpace messages.

The ErrorIcon control should be created with the FixedSize control attribute set to avoid improper sizing of the standard Windows icons.


Exit Dialog

The Exit dialog box is displayed at the end of a successful installation. This dialog box typically contains only some text and an OK button. The name of this dialog box must appear in the AdminUISequence table and InstallUISequence table with -1 as the sequence number. This is a modal dialog box.


FatalError Dialog

This modal dialog box displays at the end of an installation, if the installation is terminated because of a fatal error. This dialog box typically contains only some text and an OK button. The name of this dialog box must appear in the AdminUISequence table and InstallUISequence table with -3 as the sequence number.


FilesInUse Dialog

A FilesInUse dialog box alerts the user of processes currently running files that must be overwritten or deleted by the installation. This gives the user the opportunity to shut down these processes and avoid having to reboot the computer to complete the replacement or deletion of these files. See System Reboots.

This dialog box will be created as required by the InstallValidate action.


FirstRun Dialog

A FirstRun dialog box sequence collects user name, company name, and product ID information. The installer verifies the product ID during this dialog.

A FirstRun dialog box sequence is usually not a part of the action sequence and is instead called by the MsiCollectUserInfo function on the first run of the product.

An author of an installer package may use the template dialog sequence or create a different sequence. The dialog sequence however needs to have the user set the following properties:

USERNAME property
COMPANYNAME property
PIDKEY property

The product ID will be validated during the dialog using the ValidateProductID action or the ValidateProductID ControlEvent.

If the product ID is set as a property on the command line, or by a transform, then the necessity of having the user reenter the product ID during the first-run dialog can be circumvented by controlling the display using the ProductID property. Following the successful validation of the product ID the ProductID property is set to the full valid product ID.


LicenseAgreement Dialog

This modal dialog box displays the license agreement to the user. Typically the dialog box displays the text of the agreement using a ScrollableText control and a pair of option buttons that let the user accept or reject the agreement. For legal reasons it is advisable that neither button be presented to the user as already selected by default. This forces the user to make an active choice. Authors commonly use a RadioButtonGroup control for this purpose. Note however that the focus on a dialog box does not tab to a RadioButtonGroup control until one of the buttons in the group has been selected.


Selection Dialog

This modal dialog box enables users to select particular items.

A Selection Dialog box contains a SelectionTree Control that publishes several control events. Commonly these control events are subscribed to by Text, Icon, or Bitmap controls that display a description, the size, the path, and the icon of the highlighted item.

There is a PushButton Control on the dialog box that publishes the SelectionBrowse ControlEvent and spawns a Browse Dialog. The Browse control enables the user to select a directory.

The selection tree is populated only after the CostInitialize action and CostFinalize action are called.

A Selection dialog box is commonly used to select features. The features are listed as items in a SelectionTree control and labeled with the short string of text appearing in the Title column of the Feature table. The text string in the Description column of the Feature table is published as a SelectionDescription ControlEvent and displayed by a Text control in the Selection Dialog box. The Selection tree control also publishes the handle to the icon of the highlighted item.


UserExit Dialog

This modal dialog box displays at the end of an installation that was ended by the user. This dialog box typically contains only some text and an OK button. The name of this dialog box must appear in the AdminUISequence table and InstallUISequence table with -2 as the sequence number.


Dialog Style Bits

The style of a dialog box is specified in the Attributes column of the Dialog table by a 32-bit word composed of style bit flags.

The following list provides links to descriptions of reserved dialog box style bits.

Name | Decimal | Hexadecimal | Constant
Visible | 1 | 0x00000001 | msidbDialogAttributesVisible
Modal | 2 | 0x00000002 | msidbDialogAttributesModal
Minimize | 4 | 0x00000004 | msidbDialogAttributesMinimize
SysModal | 8 | 0x00000008 | msidbDialogAttributesSysModal
KeepModeless | 16 | 0x00000010 | msidbDialogAttributesKeepModeless
TrackDiskSpace | 32 | 0x00000020 | msidbDialogAttributesTrackDiskSpace
UseCustomPalette | 64 | 0x00000040 | msidbDialogAttributesUseCustomPalette
RTLRO | 128 | 0x00000080 | msidbDialogAttributesRTLRO
RightAligned | 256 | 0x00000100 | msidbDialogAttributesRightAligned
LeftScroll | 512 | 0x00000200 | msidbDialogAttributesLeftScroll
BiDi | 896 | 0x00000380 | msidbDialogAttributesBiDi = msidbDialogAttributesRTLRO | msidbDialogAttributesRightAligned | msidbDialogAttributesLeftScroll
Error | 65536 | 0x00010000 | msidbDialogAttributesError


BiDi Dialog Style Bit

This is a combination of the right to left reading order RTLRO, the RightAligned, and the LeftScroll dialog style bits.

Value

Decimal | Hexadecimal | Constant
896 | 0x00000380 | msidbDialogAttributesBiDi = msidbDialogAttributesRTLRO | msidbDialogAttributesRightAligned | msidbDialogAttributesLeftScroll


Error Dialog Style Bit

If this bit is set the dialog is an error dialog.

There can be more than one dialog with this style. The ErrorDialog property determines which dialog is used as an error dialog. The selected dialog can be only one of those that have this style bit set. The error dialog must have a static text control named ErrorText. This control receives the text of the error message. The dialog should also have the seven push buttons corresponding to the possible return values. The error message determines which of these buttons are actually displayed. The displayed buttons are rearranged so they are evenly distributed on the dialog. This rearrangement changes the X coordinate of the buttons, but not the other three coordinates. Therefore it is advisable that no other control should be authored in the same horizontal region of the dialog as the buttons. If the error message specifies no button, the OK button is displayed. The Default button, First active control and Cancel button values are ignored for an error dialog. The default button defined in the error message will be assigned to all three values. The effect of pushing these buttons have to be defined in the ControlEvent Table just like for all other buttons. The title of the dialog is authored in a way similar to other dialogs. It can get overwritten by the error message if it specifies a header text after the button list.

Value

Decimal | Hexadecimal | Constant
65536 | 0x00010000 | msidbDialogAttributesError


KeepModeless Dialog Style Bit

Normally, when this bit is not set and a dialog is created through DoAction, all other (typically modeless) dialogs are destroyed. If this bit is set, the other dialogs stay alive when this dialog is created.

Value

Decimal | Hexadecimal | Constant
16 | 0x00000010 | msidbDialogAttributesKeepModeless


LeftScroll Dialog Style Bit

If this style bit is set the scroll bar is located on the left side of the dialog.

Value

Decimal | Hexadecimal | Constant
512 | 0x00000200 | msidbDialogAttributesLeftScroll


Minimize Dialog Style Bit

If this bit is set, the dialog box can be minimized. This bit is ignored for modal dialog boxes, which cannot be minimized.

Value

Decimal | Hexadecimal | Constant
4 | 0x00000004 | msidbDialogAttributesMinimize


Modal Dialog Style Bit

If this bit is set, the dialog is modal, other dialogs of the same application cannot be put on top of it, and the dialog keeps the control while it is running. If this bit is not set, the dialog is modeless, other dialogs of the same application may be moved on top of it. After a modeless dialog is created and displayed, the user interface returns control to the installer. The installer then calls the user interface periodically to update the dialog and to give it a chance to process the messages. As soon as this is done, the control is returned to the installer.

Note There should be no modeless dialogs in a wizard sequence, since this would return control to the installer, ending the wizard sequence prematurely.

Value

Decimal | Hexadecimal | Constant
2 | 0x00000002 | msidbDialogAttributesSysModal


RightAligned Dialog Style Bit

If this style bit is set the text is aligned on the right side of the dialog.

Value

Decimal | Hexadecimal | Constant
256 | 0x00000100 | msidbDialogAttributesRightAligne


RTLRO Dialog Style Bit

If this style bit is set the text in the dialog is displayed in a Right-To-Left-Reading-Order.

Value

Decimal | Hexadecimal | Constant
128 | 0x00000080 | msidbDialogAttributesRTLRO


SysModal Dialog Style Bit

If this style bit is set the dialog will stop all other applications and no other applications can take the focus. This state remains until the SysModal dialog is dismissed.

Value

Decimal | Hexadecimal | Constant
8 | 0x00000008 | msidbDialogAttributesSysModal


TrackDiskSpace Dialog Style Bit

If this bit is set, the dialog periodically calls the installer. If the property changes, it notifies the controls on the dialog. This style can be used if there is a control on the dialog indicating whether you are out of disk space. If the user switches to another application and adds or removes files or otherwise modifies the available disk space, you can quickly catch the change using this style.

Any dialog relying on the OutOfDiskSpace property to determine whether to bring up a dialog must set the TrackDiskSpace Dialog Style Bit for the dialog to dynamically update space on the target volumes.

Value

Decimal | Hexadecimal | Constant
32 | 0x00000020 | msidbDialogAttributesTrackDiskSpace


UseCustomPalette Dialog Style Bit

If this bit is set, the pictures on the dialog are created with the custom palette (one per dialog received from the first control created). If the bit is not set, the pictures are rendered using a default palette.

Typically one would set this bit if the dialog contains a picture with a special palette, or several pictures sharing a custom palette. The bit should be unset if the dialog contains several pictures with different palettes. In this case the default is most likely to give a satisfactory result for all pictures.

Value

Decimal | Hexadecimal | Constant
64 | 0x00000040 | msidbDialogAttributesUseCustomPalette


Visible Dialog Style Bit

If this bit is set the dialog is originally created as visible, otherwise it is hidden.

Value

Decimal | Hexadecimal | Constant
1 | 0x00000001 | msidbDialogAttributesVisible


Controls

Developers of installation packages can author a user interface containing the following controls. For information on how to add a particular control to a dialog box, see the topic for the control and read the section Adding Controls and Text.

Some controls, such as CheckBox and ComboBox, are associated with a property specified in the Property column of the Control table. A user changes the value of this property by interacting with the control. Passive controls, such as Billboard and bitmap, are not associated with such a property.

Note that for security reasons, private properties cannot be changed by the user interacting with the user interface. If a property is to be set by the user interface it needs to be a public property and have a name in all upper case. See also About Properties.

In some cases a control may be redrawn incorrectly when canceling out of a dialog. This has to do with the order in which the controls receive WM_PAINT messages after the Cancel dialog is removed. To fix this, try changing the order of the controls in the Control table.

Control name | Associated property | Brief description of control
Billboard | No | Displays billboards based on progress messages.
Bitmap | No | Displays a static picture of a bitmap.
CheckBox | Yes | A two-state check box.
ComboBox | Yes | A drop-down list with an edit field.
DirectoryCombo | Yes | Select all except the last segment of the path.
DirectoryList | Yes | Displays folders below the main part of path.
Edit | Yes | A regular edit field for any string or integer.
GroupBox | No | Displays a rectangle that groups other controls together.
Icon | No | Displays a static picture of an icon.
Line | No | Displays a horizontal line.
ListBox | Yes | A drop-down list without an edit field.
ListView | Yes | Displays a column of values with icons for selection.
MaskedEdit | Yes | An edit field with a mask in the text field.
PathEdit | Yes | Displays folder name or entire path in an edit field.
ProgressBar Control | No | Bar graph that changes length as it receives progress messages.
PushButton | No | Displays a basic push button.
RadioButtonGroup | Yes | A group of radio buttons.
ScrollableText | No | Displays a long string of text.
SelectionTree | Yes | Displays information from the Feature Table and enables the user to change their selection state.
Text | No | Displays static text.
VolumeCostList | No | Displays costing information on different volumes.
VolumeSelectCombo | Yes | Select a volume from an alphabetical list.


Billboard Control

Billboards display commonly used controls that are added and removed from the dialog box by control events. Only controls that are not associated with a property, such as a Text, Bitmap, or Icon or a custom control can be placed on a billboard. A typical use for a Billboard control is to display progress messages.

Control Attributes

You can use the following attributes with this control. To change the value of an attribute using an event, subscribe the control to a ControlEvent in the EventMapping table and list the attribute's identifier in the Attribute column. Enter the Identifier of the ControlEvent in the Event column.

Attribute identifier | Hexadecimal bit | Description
BillboardName |  | Name of the current billboard. Enter the billboard's identifier in the Billboard column of the BBControl table.
Position |  | Position of control in the dialog box. Enter the control's width, height, and coordinates of the control's left corner into the Width, Height, X, and Y columns of the BBControl table. Use pixels for units of length and distance.
Visible | 0x00000000 0x00000001 | Hidden control. Visible control. Include this bit in the bit word of the Attributes column in the BBControl table.to make the control visible or hidden upon its creation. You can also hide or show a control by using the ControlCondition table.
Sunken | 0x00000000 0x00000004 | Display the default visual style. Display the control with a sunken, 3-D, look. Include these bits in the bit word in the Attributes column of the Control table.

Remarks

This control has no window of its own.

Billboard controls that appear in the Full user interface are listed in the Billboard table.

Controls that are located on a billboard must be listed in the BBControl table rather than the Control table.


Bitmap Control

This control displays a static picture of a bitmap.

Control Attributes

You can use the following attributes with this control. To change the value of an attribute using an event, subscribe the control to a ControlEvent in the EventMapping table and list the attribute's identifier in the Attribute column. Enter the Identifier of the ControlEvent in the Event column.

Attribute identifier Hexadecimal bit Description
Position Position of control in the dialog box.

Enter the control's width, height, and coordinates of the control's left corner into the Width, Height, X, and Y columns of the Control table or BBControl table. Use pixels for units of length and distance.
Text Contains the name of a bitmap stored in the Binary table or the handle to a bitmap or icon loaded into memory at run-time.

To display a bitmap that is stored in the Binary table, do not set the ImageHandle attribute and enter the name of the image's record appearing in the Binary table into the Text column of the Control table record for this control.

To set the bitmap image at run-time, set the ImageHandle control attribute in the Attributes of the Control table. At run-time, the Text control attribute is the handle to a bitmap loaded into memory. The control must subscribe to a control event listed in the EventMapping table with the Text control attribute specified in the Attribute column.
Visible 0x00000000

0x00000001

 Hidden control.

Visible control.

Include this bit in the bit word of the Attributes column in the Control table or BBControl table.to make the control visible or hidden upon its creation.

You can also hide or show a control by using the ControlCondition table.
Sunken 0x00000000

0x00000004

 Display the default visual style.

Display the control with a sunken, 3-D look.

Include these bits in the bit word in the Attributes column of the Control table.
ImageHandle 0x00000000

0x00010000

 See the description of the Text control attribute for this control. If the ImageHandle attribute is included in the Attributes column of the Control table, the Text control attribute contains a handle to a bitmap that is loaded into memory at run-time. If the ImageHandle attribute is not included in Attributes, the Text Control attribute is the name of the bitmap image and must be authored into the Text column of the Control table. This name is a key into the record of the Binary table containing the bitmap image.
FixedSize Control 0x00000000

0x00100000

 Stretch the bitmap image to fit the control.

Crop or center the bitmap image in the control.

Include this bit in the bit word of the Attributes column of the BBControl table or the Control table.

Remarks

This control is created as a "STATIC" with the SS_BITMAP, SS_CENTERIMAGE, WS_CHILD, and WS_GROUP styles.


CheckBox Control

This control is a two-state check box. To associate an integer or string property with this control, enter the property's name into the Property column of the Control table. The checked state of the box sets the property to the value specified in the Value column of the CheckBox table or to the initial value of the property specified in the Property table. If the property has no initial value, the checked state sets it to 1. The unchecked state sets the property to Null.

Control Attributes

You can use the following attributes with this control. To change the value of an attribute using an event, subscribe the control to a ControlEvent in the EventMapping table and list the attribute's identifier in the Attribute column. Enter the Identifier of the ControlEvent in the Event column.

Attribute identifier | Hexadecimal bit | Description
IndirectPropertyName | This is the name of an indirect property associated with the control. If the Indirect attribute bit is set, the control displays or changes the value of the property having this name. If the Indirect attribute bit is set, this name is also the value of the property listed in the Property column of the Control table.
Position Position of control in the dialog box.

Enter the control's width, height, and coordinates of the control's left corner into the Width, Height, X, and Y columns of the Control table. Use pixels for units of length and distance.
PropertyName | This is the name of the property associated with this control. If the Indirect attribute bit is not set, the control displays or changes the value of the property having this name. This attribute is specified in the Property column of the Control table.
PropertyValue | Current value of the property displayed or changed by this control. If the Indirect attribute bit is not set, this is the value of PropertyName. If the Indirect attribute bit is set, this is the value of IndirectPropertyName. If the attribute changes, the control reflects the new value.
Text This control attribute can specify the text displayed by the control, an image stored in the Binary table, or an image set at run-time.

To specify text, enter the text string into the Text column of the Control table. To set the font and font style of this text, prefix the string of displayed characters with {\style}. Where style is an identifier listed in the TextStyle column of the TextStyle table. Use {&style} to apply the base font and font style.

To specify an icon or bitmap image stored in the Binary table, do not set the ImageHandle control attribute and enter the primary key of the image's record from the Name column of the Binary table into the Text column of the Control table record for the control.

To specify an icon or bitmap image loaded into memory at run-time, set the ImageHandle control attribute in the Attribtes column of the Control table. The control must subscribe to a control event listed in the EventMapping table with the Text control attribute specified in the Attribute column. At run-time, the Text control attribute is the handle to an icon or bitmap loaded into memory.
Visible 0x00000000

0x00000001

 Hidden control.

Visible control.

Include this bit in the bit word of the Attributes column in the Control table to make the control visible or hidden upon its creation.

You can also hide or show a control by using the ControlCondition table.
Enabled 0x00000000

0x00000002

 Control in a disabled state.

Control in an enabled state.

Include this bit the bit word in the Attributes column of the Control to enable the control on creation.

You can also enable or disable a control by using the ControlCondition table.
Sunken 0x00000000

0x00000004

 Display the default visual style.

Display the control with a sunken, 3D, look.

Include these bits in the bit word in the Attributes column of the Control table.
Indirect 0x00000000

0x00000008

 The control displays or changes the value of the property in the Property column of the Control table.

The control displays or changes the value of the property that has the Identifier listed in the Property column of the Control table.

Determines if the property associated with this control is referenced indirectly.
Integer 0x00000000

0x00000010

 Property associated with the control is a string value.

Property associated with the control is an integer value.

Include this bit in the bit word of the Attributes column of the Control table to set this attribute on creation of the control.
RTLRO 0x00000000

0x00000020

 Text in the control is displayed in a Left-To-Right-Reading-Order.

Text in the control is displayed in a Right-To-Left-Reading-Order.
RightAligned 0x00000000

0x00000040

 Text in the control is aligned on the left.

Text in the control is aligned on the right.
PushLike 0x00000000

0x00020000

 Control is drawn with its usual appearance.

Control has the BS_PUSHLIKE style, and is drawn to appear as a push button.

Include this bit in the bit word of the Attributes column of the Control table to set this attribute on creation of the control.

Remarks

The control is created with the "BUTTON" class. It has the BS_CHECKBOX, WS_TABSTOP, WS_GROUP, WS_CHILD and BS_MULTILINE styles.


ComboBox Control

The ComboBox control displays a drop-down list of predefined values and an edit field into which the user can enter a value. To associate this control with a string or integer property, enter the property's name in the Property column of the Control table.

Control Attributes

You can use the following attributes with this control. To change the value of an attribute using an event, subscribe the control to a ControlEvent in the EventMapping table and list the attribute's identifier in the Attribute column. Enter the Identifier of the ControlEvent in the Event column.

Attribute identifier | Hexadecimal bit | Description
IndirectPropertyName |  | This is the name of an indirect property associated with the control. If the Indirect attribute bit is set, the control displays or changes the value of the property having this name. If the Indirect attribute bit is set, this name is also the value of the property listed in the Property column of the Control table.
Position |  | Position of control in the dialog box. Enter the control's width, height, and coordinates of the control's left corner into the Width, Height, X, and Y columns of the Control table. Use pixels for units of length and distance.
PropertyName |  | This is the name of the property associated with this control. If the Indirect attribute bit is not set, the control displays or changes the value of the property having this name. This attribute is specified in the Property column of the Control table.
PropertyValue |  | Current value of the property displayed or changed by this control. If the Indirect attribute bit is not set, this is the value of PropertyName. If the Indirect attribute bit is set, this is the value of IndirectPropertyName. If the attribute changes, the control reflects the new value.
Text |  | To set the font and font style of the property contents displayed in the edit field, enter {\style} into the Text column of the Control table, where style is an identifier listed in the TextStyle column of the TextStyle table. Use {&style} to apply the base font and font style. To specify the number of characters the user can enter, append {n} after any font specifications, where n is a positive integer.
Visible | 0x00000000 0x00000001 | Hidden control. Visible control. Include this bit in the bit word of the Attributes column in the Control table to make the control visible or hidden upon its creation. You can also hide or show a control by using the ControlCondition table.
Enabled | 0x00000000 0x00000002 | Control in a disabled state. Control in an enabled state. Include this bit the bit word in the Attributes column of the Control to enable the control on creation. You can also enable or disable a control by using the ControlCondition table.
Sunken | 0x00000000 0x00000004 | Display the default visual style. Display the control with a sunken, 3D, look. Include these bits in the bit word in the Attributes column of the Control table.
Indirect | 0x00000000 0x00000008 | The control displays or changes the value of the property in the Property column of the Control table. The control displays or changes the value of the property that has the Identifier listed in the Property column of the Control table. Determines if the property associated with this control is referenced indirectly.
Integer | 0x00000000 0x00000010 | Property associated with the control is a string value. Property associated with the control is an integer value. Include this bit in the bit word of the Attributes column of the Control table to set this attribute on creation of the control.
RTLRO | 0x00000000 0x00000020 | Text in the control is displayed in a Left-To-Right-Reading-Order. Text in the control is displayed in a Right-To-Left-Reading-Order.
RightAligned | 0x00000000 0x00000040 | Text in the control is aligned on the left. Text in the control is aligned on the right.
LeftScroll | 0x00000000 0x00000080 | The scroll bar is located on the right side of the control. The scroll bar is located on the left side of the control.
BiDi | 0x000000E0 | Set this value for a combination of the RTLRO, RightAligned, and LeftScroll attributes.
Sorted | not set 0x00010000 | Items displayed in alphabetical order. Items displayed in order specified in the ListView table. The control queries the ComboBox table, and if the Sorted style bit is set, the ComboBox has the CBS_SORT style and displays items as specified by Ordering. If this style bit is not set, items are displayed in alphabetical order.
ComboList | not set 0x00020000 | Combo box with edit field. Combo box with edit field is replaced by a static text field.
UsersLanguage | 0x00000000 0x00100000 | Fonts created in the database codepage. Fonts created in the user's default UI codepage.

Remarks

The control is created with the "COMBOBOX" class with the CBS_AUTOHSCROLL, WS_TABSTOP, WS_GROUP, WS_CHILD styles. If the ComboList bit is on, it also has the CBS_DROPDOWNLIST style, otherwise it has the CBS_DROPDOWN style.

The length of the text that can be entered can be limited by putting a number from 0 to 2147483646 in curly braces at the beginning of the Text field in the Control Table. For example if the text field starts with {80}, the length of the string is limited at 80 characters. If no such limit is supplied in the table, or if 0 is specified, the length is set to the maximum possible (2147483646 characters). A negative or non-numeric value will generate an error.

For compatibility with screenreaders, when authoring a dialog with an ComboBox control as the first active control, you must make the text field belonging to the edit field the first active control in the Dialog Table. Since the static text cannot take focus, when the dialog is created the edit field will have the focus initially as intended, but doing this ensures that screenreaders show the correct information.


DirectoryCombo Control

A DirectoryCombo control displays a part of the path that is currently displayed in the PathEdit control. The DirectoryCombo control does not show the last segment of the path, this segment is displayed by the DirectoryList control.

The DirectoryCombo Control displays all the available volumes in alphabetical order and the hierarchical steps of the current path. If the selected path contains any folders that do not exist, those files are displayed with a different icon. The types of volumes displayed are specified using the bits associated with the RemovableVolume, FixedVolume, RemoteVolume, CDROMVolume, RAMDiskVolume, and FloppyVolume control attributes.

The PathEdit, DirectoryCombo, and DirectoryList controls are associated with the same string valued property. That property is the path selected by the user. Enter the property's name into the Property column of the Control table. This property must have an initial value containing at least a one volume and one sublevel. Specify the initial value for the property in the Value column of the Property table.

This control is intended to be used on a Browse Dialog together with the PathEdit and DirectoryList controls.

Control Attributes

You can use the following attributes with this control. To change the value of an attribute using an event, subscribe the control to a ControlEvent in the EventMapping table and list the attribute's identifier in the Attribute column. Enter the Identifier of the ControlEvent in the Event column.

Attribute identifier | Hexadecimal bit | Description
IndirectPropertyName |  | This is the name of an indirect property associated with the control. If the Indirect attribute bit is set, the control displays or changes the value of the property having this name. If the Indirect attribute bit is set, this name is also the value of the property listed in the Property column of the Control table.
Position |  | Position of control in the dialog box. Enter the control's width, height, and coordinates of the control's left corner into the Width, Height, X, and Y columns of the Control table. Use pixels for units of length and distance.
PropertyName |  | This is the name of the property associated with this control. If the Indirect attribute bit is not set, the control displays or changes the value of the property having this name. This attribute is specified in the Property column of the Control table.
PropertyValue |  | Current value of the property displayed or changed by this control. If the Indirect attribute bit is not set, this is the value of PropertyName. If the Indirect attribute bit is set, this is the value of IndirectPropertyName. If the attribute changes, the control reflects the new value.
Text |  | To set the font and font style of the property contents displayed in the edit field, enter {\style} into the Text column of the Control table, where style is an identifier listed in the TextStyle column of the TextStyle table. Use {&style} to apply the base font and font style.
Visible | 0x00000000 0x00000001 | Hidden control. Visible control. Include this bit in the bit word of the Attributes column in the Control table to make the control visible or hidden upon its creation. You can also hide or show a control by using the ControlCondition table.
Enabled | 0x00000000 0x00000002 | Control in a disabled state. Control in an enabled state. Include this bit in the bit word in the Attributes column of the Control table to enable the control on creation. You can also enable or disable a control by using the ControlCondition table.
Sunken | 0x00000000 0x00000004 | Display the default visual style. Display the control with a sunken, 3D, look. Include these bits in the bit word in the Attributes column of the Control table.
Indirect | 0x00000000 0x00000008 | The control displays or changes the value of the property in the Property column of the Control table. The control displays or changes the value of the property that has the Identifier listed in the Property column of the Control table. Determines if the property associated with this control is referenced indirectly.
RTLRO | 0x00000000 0x00000020 | Text in the control is displayed in a Left-To-Right-Reading-Order. Text in the control is displayed in a Right-To-Left-Reading-Order.
RightAligned | 0x00000000 0x00000040 | Text in the control is aligned on the left. Text in the control is aligned on the right.
LeftScroll | 0x00000000 0x00000080 | The scroll bar is located on the right side of the control. The scroll bar is located on the left side of the control.
BiDi | 0x000000E0 | Set this value for a combination of the RTLRO, RightAligned, and LeftScroll attributes.
RemovableVolume | 0x00010000 | Control lists removable drives. Include in the bit word in the Attributes column of the Control table.
FixedVolume | 0x00020000 | Control lists fixed internal hard drives. Include in the bit word in the Attributes column of the Control table.
RemoteVolume | 0x00040000 | Control lists remote volumes. Include in the bit word in the Attributes column of the Control table.
CDROMVolume | 0x00080000 | Control lists CD-ROM volumes. Include in the bit word in the Attributes column of the Control table.
RAMDiskVolume | 0x00100000 | Control lists RAM disks. Include in the bit word in the Attributes column of the Control table..
FloppyVolume | 0x00200000 | Control lists floppy drives. Include in the bit word in the Attributes column of the Control table.

Remarks

The control is created with the "COMBOBOX" class with the CBS_DROPDOWNLIST, CBS_OWNERDRAWFIXED, CBS_HASSTRINGS, WS_CHILD, WS_GROUP, WS_TABSTOP and WS_VSCROLL styles.


DirectoryList Control

A DirectoryList control displays a part of the path that is currently displayed in the PathEdit control. The DirectoryList control displays the folders below the directory currently displayed by the DirectoryCombo control. If any of these folders that do not exist, they are displayed with a different icon.

The PathEdit, DirectoryCombo, and DirectoryList controls are associated with the same string valued property. That property is the path selected by the user. Enter the property's name into the Property column of the Control table. This property must have an initial value containing at least a one volume and one sublevel. Specify the initial value for the property in the Value column of the Property table.

This control is intended to be used on a Browse Dialog together with the PathEdit and DirectoryList controls.

The DirectoryList control publishes the following ControlEvents.

Control event | Description
DirectoryListNew | Create a new folder and select the name field for editing.
IgnoreChange | Highlight, but do not open, a folder in the current directory.
DirectoryListUp | Select the parent of the present directory.
DirectoryListOpen | Select and highlight a directory.

The contents of the Text field of the Control table is never displayed by the DirectoryList control. Instead this field specifes the style of text to be displayed by the control and contains a description of the control used by screen review utilities. To set the font and font style of the text displayed by the control, begin the Text column of the Control table with {\style}, where style is an identifier listed in the TextStyle column of the TextStyle table. Use {&style} to apply the base font and font style. The information following this is read by screen review utilities as the description of the control. See Accessibility.

Control Attributes

You can use the following attributes with this control. To change the value of an attribute using an event, subscribe the control to a ControlEvent in the EventMapping table and list the attribute's identifier in the Attribute column. Enter the Identifier of the ControlEvent in the Event column.

Attribute identifier | Hexadecimal bit | Description
IndirectPropertyName |  | This is the name of an indirect property associated with the control. If the Indirect attribute bit is set, the control displays or changes the value of the property having this name. If the Indirect attribute bit is set, this name is also the value of the property listed in the Property column of the Control table.
Position |  | Position of control in the dialog box. Enter the control's width, height, and coordinates of the control's left corner into the Width, Height, X, and Y columns of the Control table. Use pixels for units of length and distance.
PropertyName |  | This is the name of the property associated with this control. If the Indirect attribute bit is not set, the control displays or changes the value of the property having this name. This attribute is specified in the Property column of the Control table.
PropertyValue |  | Current value of the property displayed or changed by this control. If the Indirect attribute bit is not set, this is the value of PropertyName. If the Indirect attribute bit is set, this is the value of IndirectPropertyName. If the attribute changes, the control reflects the new value.
Text |  | To display text in screen readers, enter the text into the Text column of the Control table. See Accessibility.
Visible | 0x00000000 0x00000001 | Hidden control. Visible control. Include this bit in the bit word of the Attributes column in the Control table.to make the control visible or hidden upon its creation. You can also hide or show a control by using the ControlCondition table.
Enabled | 0x00000000 0x00000002 | Control in a disabled state. Control in an enabled state. Include this bit in the bit word in the Attributes column of the Control to enable the control on creation. You can also enable or disable a control by using the ControlCondition table.
Sunken | 0x00000000 0x00000004 | Display the default visual style. Display the control with a sunken, 3D, look. Include these bits in the bit word in the Attributes column of the Control table.
Indirect | 0x00000000 0x00000008 | The control displays or changes the value of the property in the Property column of the Control table. The control displays or changes the value of the property that has the Identifier listed in the Property column of the Control table. Determines if the property associated with this control is referenced indirectly.
RTLRO | 0x00000000 0x00000020 | Text in the control is displayed in a Left-To-Right-Reading-Order. Text in the control is displayed in a Right-To-Left-Reading-Order.
RightAligned | 0x00000000 0x00000040 | Text in the control is aligned on the left. Text in the control is aligned on the right.
LeftScroll | 0x00000000 0x00000080 | The scroll bar is located on the right side of the control. The scroll bar is located on the left side of the control.
BiDi Control | 0x000000E0 | Set this value for a combination of the RTLRO, RightAligned, and LeftScroll attributes.

Remarks

The control is created with the WC_LISTVIEW class with the LVS_LIST, LVS_EDITLABELS, WS_VSCROLL, LVS_SHAREIMAGELISTS, LVS_AUTOARRANGE, LVS_SINGLESEL, WS_BORDER, LVS_SORTASCENDING, WS_CHILD, WS_GROUP, WS_TABSTOP styles.

This control enables the user to select a subfolder of the current selection. With additional buttons it also lets the user select a new phantom folder in current selection or step up one step in the path. If the user chooses the create new folder button in a folder where there is a phantom folder already, this folder is selected for editing instead of creating a second phantom folder.


Edit Control

This control is an edit field that is associated with a string or integer value property. Enter the property's name into the Property column of the Control table.

Control Attributes

You can use the following attributes with this control. To change the value of an attribute using an event, subscribe the control to a ControlEvent in the EventMapping table and list the attribute's identifier in the Attribute column. Enter the Identifier of the ControlEvent in the Event column.

Attribute identifier | Hexadecimal bit | Description
IndirectPropertyName |  | This is the name of an indirect property associated with the control. If the Indirect attribute bit is set, the control displays or changes the value of the property having this name. If the Indirect attribute bit is set, this name is also the value of the property listed in the Property column of the Control table.
Position |  | Position of control in the dialog box. Enter the control's width, height, and coordinates of the control's left corner into the Width, Height, X, and Y columns of the Control table. Use pixels for units of length and distance.
PropertyName |  | This is the name of the property associated with this control. If the Indirect attribute bit is not set, the control displays or changes the value of the property having this name. This attribute is specified in the Property column of the Control table.
PropertyValue |  | Current value of the property displayed or changed by this control. If the Indirect attribute bit is not set, this is the value of PropertyName. If the Indirect attribute bit is set, this is the value of IndirectPropertyName. If the attribute changes, the control reflects the new value.
Text |  | To set the font and font style of the property contents displayed in the edit field, enter {\style} into the Text column of the Control table. Where style is an identifier listed in the TextStyle column of the TextStyle table. Use {&style} to apply the base font and font style. To specify the number of characters the user can enter, append {n} after any font specifications. Where n is a positive integer.
Visible | 0x00000000 0x00000001 | Hidden control. Visible control. Include this bit in the bit word of the Attributes column in the Control table to make the control visible or hidden upon its creation. You can also hide or show a control by using the ControlCondition table.
Enabled | 0x00000000 0x00000002 | Control in a disabled state. Control in an enabled state. Include this bit in the bit word in the Attributes column of the Control to enable the control on creation. You can also enable or disable a control by using the ControlCondition table.
Sunken | 0x00000000 0x00000004 | Display the default visual style. Display the control with a sunken, 3D, look. Include these bits in the bit word in the Attributes column of the Control table.
Indirect | 0x00000000 0x00000008 | The control displays or changes the value of the property in the Property column of the Control table. The control displays or changes the value of the property that has the Identifier listed in the Property column of the Control table. Determines if the property associated with this control is referenced indirectly.
Integer | 0x00000000 0x00000010 | Property associated with the control is a string value. Property associated with the control is an integer value. Include this bit in the bit word of the Attributes column of the Control table to set this attribute on creation of the control.
RTLRO | 0x00000000 0x00000020 | Text in the control is displayed in a Left-To-Right-Reading-Order. Text in the control is displayed in a Right-To-Left-Reading-Order.
RightAligned | 0x00000000 0x00000040 | Text in the control is aligned on the left. Text in the control is aligned on the right.
LeftScroll | 0x00000000 0x00000080 | The scroll bar is located on the right side of the control. The scroll bar is located on the left side of the control.
BiDi | 0x000000E0 | Set this value for a combination of the RTLRO, RightAligned, and LeftScroll attributes.
MultiLine | 0x00010000 | Creates a multiple line edit control with a vertical scroll bar. Include 65536 in the bit word in the Attributes column of the Control to create a multiple line edit control with a vertical scroll bar.
Password | 0x00200000 | Creates an edit control for entering passwords. Add 2097152 to the value in the Attributes column of the Control table to create an edit control that displays each character as an asterisk (*) as theyare typed into the control. This attribute is not available with Windows Installer version 1.0.

Remarks

The control is created with the "EDIT" class with the WS_BORDER, WS_CHILD, WS_TABSTOP, WS_GROUP styles.

The length of the text that can be entered can be limited by putting a number from 0 to 2147483646 in curly braces at the beginning of the Text field in the Control Table. For example if the text field starts with {80}, the length of the string is limited at 80 characters. If no such limit is supplied in the table, or if 0 is specified, the length is set to the maximum possible (2147483646 characters). A negative or non-numeric value will generate an error.

For compatibility with screenreaders, when authoring a dialog with an Edit control as the first active control, you must make the text field belonging to the edit field the first active control in the Dialog Table. Since the static text cannot take focus, when the dialog is created the edit field will have the focus initially as intended, but doing this ensures that screenreaders show the correct information.


GroupBox Control

This control displays a rectangle, possibly with some caption, that serves group other controls together on the dialog box.

Control Attributes

You can use the following attributes with this control. To change the value of an attribute using an event, subscribe the control to a ControlEvent in the EventMapping table and list the attribute's identifier in the Attribute column. Enter the Identifier of the ControlEvent in the Event column.

Attribute identifier | Hexadecimal bit | Description
Position |  | Position of control in the dialog box. Enter the control's width, height, and coordinates of the control's left corner into the Width, Height, X, and Y columns of the Control table or BBControl table. Use pixels for units of length and distance.
Text |  | Caption displayed in the upper left corner of the control. To set the font and font style of a text string, prefix the string of characters to be displayed with {\style}. Where style is an identifier listed in the TextStyle column of the TextStyle table. Use {&style} to apply the base font and font style.
Visible | 0x00000000 0x00000001 | Hidden control. Visible control. Include this bit in the bit word of the Attributes column in the Control table or BBControl table.to make the control visible or hidden upon its creation. You can also hide or show a control by using the ControlCondition table.
Sunken | 0x00000000 0x00000004 | Display the default visual style. Display the control with a sunken, 3-D look. Include these bits in the bit word in the Attributes column of the Control table.
RTLRO | 0x00000000 0x00000020 | Text in the control is displayed in a Left-To-Right-Reading-Order. Text in the control is displayed in a Right-To-Left-Reading-Order.
RightAligned | 0x00000000 0x00000040 | Text in the control is aligned on the left. Text in the control is aligned on the right.

Remarks

The control is created as a "BUTTON" with the BS_GROUPBOX, WS_CHILD, WS_GROUP styles.

There is always a gap between the top of the control's window and the visible frame, even when there is no caption.


Icon Control

This control displays a static picture of an icon. The background of the image is transparent.

Control Attributes

You can use the following attributes with this control. To change the value of an attribute using an event, subscribe the control to a ControlEvent in the EventMapping table and list the attribute's identifier in the Attribute column. Enter the Identifier of the ControlEvent in the Event column.

Attribute identifier Hexadecimal bit Description
Position Position of control in the dialog box.

Enter the control's width, height, and coordinates of the control's left corner into the Width, Height, X, and Y columns of the Control table. Use pixels for units of length and distance.
Text Contains the name of an icon stored in the Binary table or the handle to a icon loaded into memory at run-time.

To display an icon that is stored in the Binary table, do not set the ImageHandle attribute and enter the name of the image's record appearing in the Binary table into the Text column of the Control table record for this control.

To set the icon image at run-time, set the ImageHandle control attribute in the Attributes of the Control table. At run-time, the Text control attribute is the handle to an icon loaded into memory. The control must subscribe to a control event listed in the EventMapping table with the Text control attribute specified in the Attribute column.
Visible 0x00000000

0x00000001

 Hidden control.

Visible control.

Include this bit in the bit word of the Attributes column in the Control table to make the control visible or hidden upon its creation.

You can also hide or show a control by using the ControlCondition table.
Sunken 0x00000000

0x00000004

 Display the default visual style.

Display the control with a sunken, 3-D look.

Include these bits in the bit word in the Attributes column of the Control table.
ImageHandle 0x00000000

0x00010000

 See the description of the Text control attribute for this control. If the ImageHandle attribute is included in the Attributes column of the Control table, the Text control attribute contains a handle to an icon that is loaded into memory at run-time. If the ImageHandle attribute is not included in Attributes, the Text Control attribute is the name of the icon and must be authored into the Text column of the Control table. This name is a key into the record of the Binary table containing the icon image.
FixedSize 0x00000000

0x00100000

 Stretch the icon image to fit the control.

Crop or center the icon image in the control.

Include this bit in the bit word of the Attributes column of the Control table.

IconSize 0x00000000

0x00200000

0x00400000

0x00600000

 Load the first image.

Load the first 16x16 image.

Load the first 32x32 image.

Load the first 48x48 image.

An icon file can contain different size images of the same icon. Include the value of the appropriate bit word in the Attributes column of the Control table

If these bits are not set, the installer ignores the FixedSize attribute and the image is stretched to fit the control rectangle. If both the IconSize bits and the FixedSize bits are set, an image smaller than the control is centered and an image is larger than the control it is shrunk to fit.

Remarks

This control is created as a "STATIC" with the SS_ICON, SS_CENTERIMAGE, WS_CHILD, and WS_GROUP styles.


Line Control

This control is a horizontal line.

Control Attributes

You can use the following attributes with this control. To change the value of an attribute using an event, subscribe the control to a ControlEvent in the EventMapping table and list the attribute's identifier in the Attribute column. Enter the Identifier of the ControlEvent in the Event column.

Attribute identifier | Hexadecimal bit | Description
Position |  | Position of control in the dialog box. Enter the control's width, height, and coordinates of the control's left corner into the Width, Height, X, and Y columns of the Control table or BBControl table. Use pixels for units of length and distance.
Visible | 0x00000000 0x00000001 | Hidden control. Visible control. Include this bit in the bit word of the Attributes column in the Control table or BBControl table.to make the control visible or hidden upon its creation. You can also hide or show a control by using the ControlCondition table.
Sunken | 0x00000000 0x00000004 | Display the default visual style. Display the control with a sunken, 3-D look. Include these bits in the bit word in the Attributes column of the Control table.

Remarks

The Line control is implemented is using a STATIC control with the SS_ETCHEDHORZ and SS_SUNKEN styles.


ListBox Control

This is a regular list box that enables the user to make a single selection from a list of predetermined values. The possible values are read from the Listbox Table. You can associate a string or integer property by entering the property's name in the Property column of the Control table.

Control Attributes

You can use the following attributes with this control. To change the value of an attribute using an event, subscribe the control to a ControlEvent in the EventMapping table and list the attribute's identifier in the Attribute column. Enter the Identifier of the ControlEvent in the Event column.

Attribute identifier | Hexadecimal bit | Description
IndirectPropertyName |  | This is the name of an indirect property associated with the control. If the Indirect attribute bit is set, the control displays or changes the value of the property having this name. If the Indirect attribute bit is set, this name is also the value of the property listed in the Property column of the Control table.
Position |  | Position of control in the dialog box. Enter the control's width, height, and coordinates of the control's left corner into the Width, Height, X, and Y columns of the Control table. Use pixels for units of length and distance.
PropertyName |  | This is the name of the property associated with this control. If the Indirect attribute bit is not set, the control displays or changes the value of the property having this name. This attribute is specified in the Property column of the Control table.
PropertyValue |  | Current value of the property displayed or changed by this control. If the Indirect attribute bit is not set, this is the value of PropertyName. If the Indirect attribute bit is set, this is the value of IndirectPropertyName. If the attribute changes, the control reflects the new value.
Text |  | Text displayed by screen readers. Enter the text to be displayed into the Text column of the the Control table. To set the font and font style of the text string, prefix the string of characters to be displayed with {\style}. Where style is an identifier listed in the TextStyle column of the TextStyle table. Use {&style} to apply the base font and font style.
Visible | 0x00000000 0x00000001 | Hidden control. Visible control. Include this bit in the bit word of the Attributes column in the Control table to make the control visible or hidden upon its creation. You can also hide or show a control by using the ControlCondition table.
Enabled | 0x00000000 0x00000002 | Control in a disabled state. Control in an enabled state. Include this bit in the bit word in the Attributes column of the Control to enable the control on creation. You can also enable or disable a control by using the ControlCondition table.
Sunken | 0x00000000 0x00000004 | Display the default visual style. Display the control with a sunken, 3D, look. Include these bits in the bit word in the Attributes column of the Control table.
Indirect | 0x00000000 0x00000008 | The control displays or changes the value of the property in the Property column of the Control table. The control displays or changes the value of the property that has the Identifier listed in the Property column of the Control table. Determines if the property associated with this control is referenced indirectly.
Integer | 0x00000000 0x00000010 | Property associated with the control is a string value. Property associated with the control is an integer value. Include this bit in the bit word of the Attributes column of the Control table to set this attribute on creation of the control.
RTLRO | 0x00000000 0x00000020 | Text in the control is displayed in a Left-To-Right-Reading-Order. Text in the control is displayed in a Right-To-Left-Reading-Order.
RightAligned | 0x00000000 0x00000040 | Text in the control is aligned on the left. Text in the control is aligned on the right.
LeftScroll | 0x00000000 0x00000080 | The scroll bar is located on the right side of the control. The scroll bar is located on the left side of the control.
BiDi | 0x000000E0 | Set this value for a combination of the RTLRO, RightAligned, and LeftScroll attributes.
Sorted | 0x00000000 0x00010000 | Items displayed in alphabetical order. Items displayed in order specified in the ListView table. Include this bit in the bit word in the Attributes column to display items in the order specified by the Order column of the ListView table.
UsersLanguage | 0x00000000 0x00100000 | Fonts created in the database codepage. Fonts created in the user's default UI codepage.

Remarks

The control is created with the "LISTBOX" class.

If the Sorted control style bit is on, the control is created with the LBS_NOTIFY, WS_VSCROLL, WS_BORDER styles, otherwise with the LBS_STANDARD style. It also has the WS_TABSTOP, WS_GROUP, WS_CHILD styles.


ListView Control

This is a regular ListView control that displays a single column of values with an icon next to each item. It enables the user to select a single string or integer value for a property from a predetermined list. The possible values are read from the ListView Table. You can associate the control with an integer or string value by entering the property's name into the Property column of the Control table.

The contents of the Text field of the Control table is never displayed by the ListView control. Instead this field specifes the style of text to be displayed by the control and contains a description of the control used by screen review utilities. To set the font and font style of the text displayed by the control, begin the Text column of the Control table with {\style}, where style is an identifier listed in the TextStyle column of the TextStyle table. Use {&style} to apply the base font and font style. The information following this is read by screen review utilities as the description of the control. See Accessibility.

Control Attributes

You can use the following attributes with this control. To change the value of an attribute using an event, subscribe the control to a ControlEvent in the EventMapping table and list the attribute's identifier in the Attribute column. Enter the Identifier of the ControlEvent in the Event column.

Attribute identifier | Hexadecimal bit | Description
IndirectPropertyName | This is the name of an indirect property associated with the control. If the Indirect attribute bit is set, the control displays or changes the value of the property having this name. If the Indirect attribute bit is set, this name is also the value of the property listed in the Property column of the Control table.
Position Position of control in the dialog box.

Enter the control's width, height, and coordinates of the control's left corner into the Width, Height, X, and Y columns of the Control table. Use pixels for units of length and distance.
PropertyName | This is the name of the property associated with this control. If the Indirect attribute bit is not set, the control displays or changes the value of the property having this name. This attribute is specified in the Property column of the Control table.
PropertyValue | Current value of the property displayed or changed by this control. If the Indirect attribute bit is not set, this is the value of PropertyName. If the Indirect attribute bit is set, this is the value of IndirectPropertyName. If the attribute changes, the control reflects the new value.
Text | To display text in screen readers, enter the text into the Text column of the Control table. See Accessibility.
Visible 0x00000000

0x00000001

 Hidden control.

Visible control.

Include this bit in the bit word of the Attributes column in the Control table to make the control visible or hidden upon its creation.

You can also hide or show a control by using the ControlCondition table.
Enabled 0x00000000

0x00000002

 Control in a disabled state.

Control in an enabled state.

Include this bit in the bit word in the Attributes column of the Control to enable the control on creation.

You can also enable or disable a control by using the ControlCondition table.
Sunken 0x00000000

0x00000004

 Display the default visual style.

Display the control with a sunken, 3D, look.

Include these bits in the bit word in the Attributes column of the Control table.
Indirect 0x00000000

0x00000008

 The control displays or changes the value of the property in the Property column of the Control table.

The control displays or changes the value of the property that has the Identifier listed in the Property column of the Control table.

Determines if the property associated with this control is referenced indirectly.
Integer 0x00000000

0x00000010

 Property associated with the control is a string value.

Property associated with the control is an integer value.

Include this bit in the bit word of the Attributes column of the Control table to set this attribute on creation of the control.
RTLRO 0x00000000

0x00000020

 Text in the control is displayed in a Left-To-Right-Reading-Order.

Text in the control is displayed in a Right-To-Left-Reading-Order.
RightAligned 0x00000000

0x00000040

 Text in the control is aligned on the left.

Text in the control is aligned on the right.
LeftScroll 0x00000000

0x00000080

 The scroll bar is located on the right side of the control.

The scroll bar is located on the left side of the control.

BiDi | 0x000000E0 | Set this value for a combination of the RTLRO, RightAligned, and LeftScroll attributes.
Sorted 0x00000000

0x00010000

 Items displayed in alphabetical order.

Items displayed in order specified in the ListView table.

Include this bit in the bit word in the Attributes column to display items in the order specified by the Order column of the ListView table.
FixedSize 0x00000000

0x00100000

 Stretch the icon image to fit the control.

Crop or center the icon image in the control.

Include this bit in the bit word of the Attributes column of the Control table.

IconSize 0x00000000

0x00200000

0x00400000

0x00600000

 Load the first image.

Load the first 16x16 image.

Load the first 32x32 image.

Load the first 48x48 image.

An icon file can contain different size images of the same icon. Include the value of the appropriate bit word in the Attributes column of the Control table

If these bits are not set, the installer ignores the FixedSize attribute and the image is stretched to fit the control rectangle. If both the IconSize bits and the FixedSize bits are set, an image smaller than the control is centered and an image is larger than the control it is shrunk to fit.

Remarks

The control is created with the WC_LISTVIEW class with the LVS_REPORT, LVS_NOCOLUMNHEADER, WS_VSCROLL, WS_HSCROLL, LVS_SHAREIMAGELISTS, LVS_SINGLESEL, LVS_SHOWSELALWAYS, WS_BORDER, WS_TABSTOP styles.

If the Sorted style bit is not on, the control also has the LVS_SORTASCENDING style.

For compatibility with screenreaders, when authoring a dialog with an ListView control as the first active control, you must make the text field belonging to the edit field the first active control in the Dialog Table. Since the static text cannot take focus, when the dialog is created the edit field will have the focus initially as intended, but doing this ensures that screenreaders show the correct information.


MaskedEdit Control

This is an edit field control with a mask contained in the text field of the control. You can associate the control with a string value property by entering the property's name into the Property column of the Control table.

The MaskedEdit Control can be used to create a template for user entry of information such as a phone number or Product ID code. For example, the PIDKEY property can be entered by the user through a MaskedEdit Control that has been specified by setting the PIDTemplate property to a string such as:

12345<### -%%%%%%%>@@@@@

This string defines the masking template for the entry of the PIDKEY property by the user.

The syntax of the mask is a described below. The visible segment of the string is enclosed by the pair of <> characters.

Character | Meaning
< | This is the left end of the visible segment of the template. This character and everything to its left is hidden in the user interface. There should be no more than one instance of this character in the template.
> | This is the right end of the visible segment of the template. This character and everything to its right is hidden in the user interface. This character is replaced by a dash during validation. If there is a visible segment started with <, then it must be terminated with a matching >.
# | This character is a digit.
% | An alternate digit, essentially the same as # , enabling a custom action to differentiate between fields in a way that can be controlled by the mask.
@ | This character is a randomized digit. This character should not appear in the visible part of the template.
_ | This character stands for an alpha-numeric character.
^ | An alternate alpha-numeric character, enabling a custom action to differentiate between fields in a way that can be controlled by the mask..
? | An alternate alpha-numeric character.
' | An alternate alpha-numeric character.
= | This character is the field terminator. This must follow a #, %, ^, or '. This creates one more input position of the same type as the preceding positions and terminates the field with a '-' separator.

Any other character is treated as a literal constant.

For the characters that can be edited the control creates separate edit windows with one window for each block of contiguous characters of the same kind.

Control Attributes

You can use the following attributes with this control. To change the value of an attribute using an event, subscribe the control to a ControlEvent in the EventMapping table and list the attribute's identifier in the Attribute column. Enter the Identifier of the ControlEvent in the Event column.

Attribute identifier | Hexadecimal bit | Description
IndirectPropertyName |  | This is the name of an indirect property associated with the control. If the Indirect attribute bit is set, the control displays or changes the value of the property having this name. If the Indirect attribute bit is set, this name is also the value of the property listed in the Property column of the Control table.
Position |  | Position of control in the dialog box. Enter the control's width, height, and coordinates of the control's left corner into the Width, Height, X, and Y columns of the Control table. Use pixels for units of length and distance.
PropertyName |  | This is the name of the property associated with this control. If the Indirect attribute bit is not set, the control displays or changes the value of the property having this name. This attribute is specified in the Property column of the Control table.
PropertyValue |  | Current value of the property displayed or changed by this control. If the Indirect attribute bit is not set, this is the value of PropertyName. If the Indirect attribute bit is set, this is the value of IndirectPropertyName. If the attribute changes, the control reflects the new value.
Text |  | To specify the font style and the masking template used in the edit field of this control, enter a string of text into the Text column of the Control Table. Prefix this string with {\style}. Where style is an identifier listed in the TextStyle column of the TextStyle table. Use {&style} to apply the base font and font style. The string that specifies the masking template follows this prefix and uses the syntax described above.
Visible | 0x00000000 0x00000001 | Hidden control. Visible control. Include this bit in the bit word of the Attributes column in the Control table to make the control visible or hidden upon its creation. You can also hide or show a control by using the ControlCondition table.
Enabled | 0x00000000 0x00000002 | Control in a disabled state. Control in an enabled state. Include this bit in the bit word in the Attributes column of the Control to enable the control on creation. You can also enable or disable a control by using the ControlCondition table.
Sunken | 0x00000000 0x00000004 | Display the default visual style. Display the control with a sunken, 3D, look. Include these bits in the bit word in the Attributes column of the Control table.
Indirect | 0x00000000 0x00000008 | The control displays or changes the value of the property in the Property column of the Control table. The control displays or changes the value of the property that has the Identifier listed in the Property column of the Control table. Determines if the property associated with this control is referenced indirectly.

Remarks

The control creates one parent window of the "BUTTON" class with the BS_OWNERDRAW and WS_EX_CONTROLPARENT styles. It creates several child windows to this window: for the constant text parts it creates "STATIC" windows with the SS_LEFT and WS_CHILD styles. For the editable fields it creates an "EDIT" window with the WS_CHILD, WS_BORDER and WS_TABSTOP styles. In case of a numeric field the window also has the ES_NUMBER style.

The alternate digit, %, and alternate alpha-numeric characters, ^, ?, and ' fields are intended to allow custom actions differentiate between fields in a way that can be controlled by the mask. For example, ^ could be used for fields that should be uppercase.


PathEdit Control

The PathEdit control displays an edit field that enables a user to select the tail end section of a path. This control supports entering the selected folder name or the entire path in the edit field. A user can also enter a Universal Naming Convention (UNC) path to a drive that has no drive letter. If the user enters a tail segment for the path that is invalid for the present volume, PathEdit cannot transfer the focus to the next control.

The PathEdit, DirectoryCombo, and DirectoryList controls are associated with the same string valued property. That property is the path selected by the user. Enter the property's name into the Property column of the Control table. This property must have an initial value containing at least a one volume and one sublevel. Specify the initial value for the property in the Value column of the Property table.

This control is intended to be used on a Browse Dialog together with the PathEdit and DirectoryList controls.

Control Attributes

You can use the following attributes with this control. To change the value of an attribute using an event, subscribe the control to a ControlEvent in the EventMapping table and list the attribute's identifier in the Attribute column. Enter the Identifier of the ControlEvent in the Event column.

Attribute identifier | Hexadecimal bit | Description
IndirectPropertyName |  | This is the name of an indirect property associated with the control. If the Indirect attribute bit is set, the control displays or changes the value of the property having this name. If the Indirect attribute bit is set, this name is also the value of the property listed in the Property column of the Control table.
Position |  | Position of control in the dialog box. Enter the control's width, height, and coordinates of the control's left corner into the Width, Height, X, and Y columns of the Control table. Use pixels for units of length and distance.
PropertyName |  | This is the name of the property associated with this control. If the Indirect attribute bit is not set, the control displays or changes the value of the property having this name. This attribute is specified in the Property column of the Control table.
PropertyValue |  | Current value of the property displayed or changed by this control. If the Indirect attribute bit is not set, this is the value of PropertyName. If the Indirect attribute bit is set, this is the value of IndirectPropertyName. If the attribute changes, the control reflects the new value.
Text |  | To set the font and font style of the property contents displayed in the edit field, enter {\style} into the Text column of the Control table. Where style is an identifier listed in the TextStyle column of the TextStyle table. Use {&style} to apply the base font and font style. To specify the number of characters the user can enter, append {n} after any font specifications. Where n is a positive integer.
Visible | 0x00000000 0x00000001 | Hidden control. Visible control. Include this bit in the bit word of the Attributes column in the Control table to make the control visible or hidden upon its creation. You can also hide or show a control by using the ControlCondition table.
Enabled | 0x00000000 0x00000002 | Control in a disabled state. Control in an enabled state. Include this bit in the bit word in the Attributes column of the Control to enable the control on creation. You can also enable or disable a control by using the ControlCondition table.
Sunken | 0x00000000 0x00000004 | Display the default visual style. Display the control with a sunken, 3D, look. Include these bits in the bit word in the Attributes column of the Control table.
Indirect | 0x00000000 0x00000008 | The control displays or changes the value of the property in the Property column of the Control table. The control displays or changes the value of the property that has the Identifier listed in the Property column of the Control table. Determines if the property associated with this control is referenced indirectly.
RTLRO | 0x00000000 0x00000020 | Text in the control is displayed in a Left-To-Right-Reading-Order. Text in the control is displayed in a Right-To-Left-Reading-Order.
RightAligned | 0x00000000 0x00000040 | Text in the control is aligned on the left. Text in the control is aligned on the right.

Remarks

The control is derived from the Edit control.

For compatibility with screenreaders, when authoring a dialog with an PathEdit control as the first active control, you must make the text field belonging to the edit field the first active control in the Dialog Table. Since the static text cannot take focus, when the dialog is created the edit field will have the focus initially as intended, but doing this ensures that screenreaders show the correct information.


ProgressBar Control

This control displays a bar graph that changes length as it receives progress messages. The ProgressBar control subscribes to the SetProgress control event. It can subscribe to a control event named after the action being monitored.

For related information, see Authoring a Progress Bar Control, and Adding Custom Actions to the ProgressBar.

Control Attributes

You can use the following attributes with this control. To change the value of an attribute using an event, subscribe the control to a ControlEvent in the EventMapping table and list the attribute's identifier in the Attribute column. Enter the Identifier of the ControlEvent in the Event column.

Attribute identifier | Hexadecimal bit | Description
Position |  | Position of control in the dialog box. Enter the control's width, height, and coordinates of the control's left corner into the Width, Height, X, and Y columns of the Control table. Use pixels for units of length and distance.
Progress |  | This attribute specifies how much of the progress bar is filled. The attribute is composed of two integers and a string. The first integer field is the current number of progress ticks and the second integer field is the default maximum number of progress ticks (1024). The third field is a string that is the name of the action in progress. If the current number of progress ticks is larger than the maximum, the installer changes it to the maximum. This attribute is set and changed by the SetProgress ControlEvent. You must subscribe the control to this event in the EventMapping table by entering SetProgress into the Event column and Progress into the Attribute column.
Text |  | Text displayed by the control. To set the font and font style of a text string, prefix the string of characters to be displayed with {\style}. Where style is an identifier listed in the TextStyle column of the TextStyle table. Use {&style} to apply the base font and font style.
Visible | 0x00000000 0x00000001 | Hidden control. Visible control. Include this bit in the bit word of the Attributes column in the Control table to make the control visible or hidden upon its creation. You can also hide or show a control by using the ControlCondition table.
Sunken | 0x00000000 0x00000004 | Display the default visual style. Display the control with a sunken, 3D, look. Include these bits in the bit word in the Attributes column of the Control table.
RTLRO | 0x00000000 0x00000020 | Text in the control is displayed in a Left-To-Right-Reading-Order. Text in the control is displayed in a Right-To-Left-Reading-Order.
Progress95 | 0x00000000 0x00010000 | Progress bar drawn as continuous bar. Progress bar drawn as series of rectangles. Include these bits in the bit word in the Attributes column of the Control table.

Remarks

The control is created as a PROGRESS_CLASS. It also has the WS_CHILD and WS_GROUP styles.


PushButton Control

This control displays a basic push button, also known as a command button.

Control Attributes

You can use the following attributes with this control. To change the value of an attribute using an event, subscribe the control to a ControlEvent in the EventMapping table and list the attribute's identifier in the Attribute column. Enter the Identifier of the ControlEvent in the Event column.

Attribute identifier Hexadecimal bit Description
Position Position of control in the dialog box.

Enter the control's width, height, and coordinates of the control's left corner into the Width, Height, X, and Y columns of the Control table. Use pixels for units of length and distance.
Text This control attribute can specify the text displayed by the control, an image stored in the Binary table, or an image set at run-time.

To specify text, enter the text string into the Text column of the Control table. To set the font and font style of this text, prefix the string of displayed characters with {\style}. Where style is an identifier listed in the TextStyle column of the TextStyle table. Use {&style} to apply the base font and font style.

To specify an icon or bitmap image stored in the Binary table, do not set the ImageHandle control attribute and enter the primary key of the image's record from the Name column of the Binary table into the Text column of the Control table record for the control.

To specify an icon or bitmap image loaded into memory at run-time, set the ImageHandle control attribute in the Attribtes column of the Control table. The control must subscribe to a control event listed in the EventMapping table with the Text control attribute specified in the Attribute column. At run-time, the Text control attribute is the handle to an icon or bitmap loaded into memory.
Visible 0x00000000

0x00000001

 Hidden control.

Visible control.

Include this bit in the bit word of the Attributes column in the Control table to make the control visible or hidden upon its creation.

You can also hide or show a control by using the ControlCondition table.
Enabled 0x00000000

0x00000002

 Control in a disabled state.

Control in an enabled state.

Include this bit the bit word in the Attributes column of the Control to enable the control on creation.

You can also enable or disable a control by using the ControlCondition table.
Sunken 0x00000000

0x00000004

 Display the default visual style.

Display the control with a sunken, 3D, look.

Include these bits in the bit word in the Attributes column of the Control table.
RTLRO 0x00000000

0x00000020

 Text in the control is displayed in a Left-To-Right-Reading-Order.

Text in the control is displayed in a Right-To-Left-Reading-Order.
ImageHandle 0x00000000

0x00010000

 The installer uses the ImageHandle control attribute to determine whether the Text control attribute is an image specified in the Binary table or the handle to an image loaded in memory at run-time.

To specify an icon or bitmap image stored in the Binary table, do not set the ImageHandle control attribute and enter the primary key of the image's record from the Name column of the Binary table into the Text column of the Control table record for the control.

To specify an icon or bitmap image loaded into memory at run-time, set the ImageHandle control attribute in the Attribtes column of the Control table. The control must subscribe to a control event listed in the EventMapping table with the Text control attribute specified in the Attribute column. At run-time, the Text control attribute is the handle to an icon or bitmap loaded into memory.
Bitmap 0x00000000

0x00040000

 Text in the control is specified in the Text column of the Control table.

The button has the BS_BITMAP style, text in the control is replaced by a bitmap image. The Text column in the Control table is used as a foreign key to the Binary table.

Include this bit in the bit word in the Attributes column of the Control.

Do not set the Icon and Bitmap style bits simultaneously. The button cannot contain both a bitmap image and text.

To set the font and font style of a text string, prefix the string of characters to be displayed with {\style}. Where style is an identifier listed in the TextStyle column of the TextStyle table. Use {&style} to apply the base font and font style.
Icon Control 0x00000000

0x00080000

 Text in the control is specified in the Text column of the Control table.

The button has the BS_ICON style, text in the control is replaced by an icon image. The Text column in the Control table is used as a foreign key to the Binary table.

Include this bit in the bit word in the Attributes column of the Control.

Do not set the Icon and Bitmap bits simultaneously. The button cannot contain both an icon image and text.

To set the font and font style of a text string, prefix the string of characters to be displayed with {\style}. Where style is an identifier listed in the TextStyle column of the TextStyle table. Use {&style} to apply the base font and font style.
FixedSize 0x00000000

0x00100000

 Stretch the icon image to fit the control.

Crop or center the icon image in the control.

Include this bit in the bit word of the Attributes column of the BBControl table or the Control table.

IconSize 0x00000000

0x00200000

0x00400000

0x00600000

 Load the first image.

Load the first 16x16 image.

Load the first 32x32 image.

Load the first 48x48 image.

An icon file can contain different size images of the same icon. Include the value of the appropriate bit word in the Attributes column of the Control table

If these bits are not set, the installer ignores the FixedSize attribute and the image is stretched to fit the control rectangle. If both the IconSize bits and the FixedSize bits are set, an image smaller than the control is centered and an image is larger than the control it is shrunk to fit.

Remarks

The control is created with the "BUTTON" class and uses the BS_MULTILINE, WS_CHILD, WS_TABSTOP, WS_GROUP styles.


RadioButtonGroup Control

This control is a group of radio buttons. It enables the user to select a string or integer value for a property from a predetermined list of values. You can associate this control with a property by entering the property's name into the Property column of the Control table. Specify the possible values for selection in the Value column of the RadioButton Table. Note that the string displayed is not necessarily the same as the value that the user is choosing.

RadioButtonGroup controls only set property values and cannot be used to send a control event.

The implementation treats the whole group as one control, therefore it is not possible to hide or disable individual buttons within the group. Similarly all the buttons have to be of the same style, that is, either all of them have text or all of them have bitmaps, or other similar features. The position of the buttons is authored relative to the group. This way the entire group can be moved by changing only the coordinates of the group without changing the individual buttons. At creation the control verifies that the individual buttons do not extend beyond the boundaries of the group.

Note that the focus on a dialog box will not tab to a RadioButtonGroup Control until one of the buttons in the group has been selected. To make the focus tab to this button group specify one of the buttons as a default setting for the control.

Control Attributes

You can use the following attributes with this control. To change the value of an attribute using an event, subscribe the control to a ControlEvent in the EventMapping table and list the attribute's identifier in the Attribute column. Enter the Identifier of the ControlEvent in the Event column.

Attribute identifier | Hexadecimal bit | Description
IndirectPropertyName | This is the name of an indirect property associated with the control. If the Indirect attribute bit is set, the control displays or changes the value of the property having this name. If the Indirect attribute bit is set, this name is also the value of the property listed in the Property column of the Control table.
Position Position of control in the dialog box.

Enter the control's width, height, and coordinates of the control's left corner into the Width, Height, X, and Y columns of the Control table. Use pixels for units of length and distance.
PropertyName | This is the name of the property associated with this control. If the Indirect attribute bit is not set, the control displays or changes the value of the property having this name. This attribute is specified in the Property column of the Control table.
PropertyValue | Current value of the property displayed or changed by this control. If the Indirect attribute bit is not set, this is the value of PropertyName. If the Indirect attribute bit is set, this is the value of IndirectPropertyName. If the attribute changes, the control reflects the new value.
Text This control attribute can specify the text displayed by the control, an image stored in the Binary table, or an image set at run-time.

To specify text, enter the text string into the Text column of the Control table. To set the font and font style of this text, prefix the string of displayed characters with {\style}. Where style is an identifier listed in the TextStyle column of the TextStyle table. Use {&style} to apply the base font and font style.

To specify an icon or bitmap image stored in the Binary table, do not set the ImageHandle control attribute and enter the primary key of the image's record from the Name column of the Binary table into the Text column of the Control table record for the control.

To specify an icon or bitmap image loaded into memory at run-time, set the ImageHandle control attribute in the Attribtes column of the Control table. The control must subscribe to a control event listed in the EventMapping table with the Text control attribute specified in the Attribute column. At run-time, the Text control attribute is the handle to an icon or bitmap loaded into memory.
Visible 0x00000000

0x00000001

 Hidden control.

Visible control.

Include this bit in the bit word of the Attributes column in the Control table to make the control visible or hidden upon its creation.

You can also hide or show a control by using the ControlCondition table.
Enabled 0x00000000

0x00000002

 Control in a disabled state.

Control in an enabled state.

Include this bit the bit word in the Attributes column of the Control to enable the control on creation.

You can also enable or disable a control by using the ControlCondition table.
Sunken 0x00000000

0x00000004

 Display the default visual style.

Display the control with a sunken, 3D, look.

Include these bits in the bit word in the Attributes column of the Control table.
Indirect 0x00000000

0x00000008

 The control displays or changes the value of the property in the Property column of the Control table.

The control displays or changes the value of the property that has the Identifier listed in the Property column of the Control table.

Determines if the property associated with this control is referenced indirectly.
Integer 0x00000000

0x00000010

 Property associated with the control is a string value.

Property associated with the control is an integer value.

Include this bit in the bit word of the Attributes column of the Control table to set this attribute on creation of the control.
RTLRO 0x00000000

0x00000020

 Text in the control is displayed in a Left-To-Right-Reading-Order.

Text in the control is displayed in a Right-To-Left-Reading-Order.
RightAligned 0x00000000

0x00000040

 Text in the control is aligned on the left.

Text in the control is aligned on the right.
ImageHandle 0x00000000

0x00010000

 The installer uses the ImageHandle control attribute to determine whether the Text control attribute is an image specified in the Binary table or the handle to an image loaded in memory at run-time.

To specify an icon or bitmap image stored in the Binary table, do not set the ImageHandle control attribute and enter the primary key of the image's record from the Name column of the Binary table into the Text column of the Control table record for the control.

To specify an icon or bitmap image loaded into memory at run-time, set the ImageHandle control attribute in the Attribtes column of the Control table. The control must subscribe to a control event listed in the EventMapping table with the Text control attribute specified in the Attribute column. At run-time, the Text control attribute is the handle to an icon or bitmap loaded into memory.
PushLike 0x00000000

0x00020000

 Control is drawn with its usual appearance.

Control has the BS_PUSHLIKE style, and is drawn to appear as a push button.

Include this bit in the bit word of the Attributes column of the Control table to set this attribute on creation of the control.
Bitmap 0x00000000

0x00040000

 Text in the control is specified in the Text column of the Control table.

The control has the BS_BITMAP style, text in the control is replaced by a bitmap image. The Text column in the Control table is used as a foreign key to the Binary table.

Include this bit in the bit word in the Attributes column of the Control table.

Do not set the Icon and Bitmap style bits simultaneously. The button cannot contain both a bitmap image and text.

To set the font and font style of a text string, prefix the string of characters to be displayed with {\style}. Where style is an identifier listed in the TextStyle column of the TextStyle table. Use {&style} to apply the base font and font style.
Icon 0x00000000

0x00080000

 Text in the control is specified in the Text column of the Control table.

The control has the BS_ICON style, text in the control is replaced by an icon image. The Text column in the Control table is used as a foreign key to the Binary table.

Include this bit in the bit word in the Attributes column of the Control table.

Do not set the Icon and Bitmap bits simultaneously. The button cannot contain both an icon image and text.

To set the font and font style of a text string, prefix the string of characters to be displayed with {\style}. Where style is an identifier listed in the TextStyle column of the TextStyle table. Use {&style} to apply the base font and font style.
FixedSize 0x00000000

0x00100000

 Stretch the icon image to fit the control.

Crop or center the icon image in the control.

Include this bit in the bit word of the Attributes column of the Control table.

IconSize 0x00000000

0x00200000

0x00400000

0x00600000

 Load the first image.

Load the first 16x16 image.

Load the first 32x32 image.

Load the first 48x48 image.

An icon file can contain different size images of the same icon. Include the value of the appropriate bit word in the Attributes column of the Control table

If these bits are not set, the installer ignores the FixedSize attribute and the image is stretched to fit the control rectangle. If both the IconSize bits and the FixedSize bits are set, an image smaller than the control is centered and an image is larger than the control it is shrunk to fit.
HasBorder not set

0x01000000

 No border and no text.

Display border and text.

Include 16777216 in the bit word in the Attributes column of the Control to display a border and text.

Remarks

Because of the way Windows draws the frame, there is a gap between the top of the control's window and the visible frame, even when there is no caption.

The group is created using the "BUTTON" class. If the HasBorder bit is set, it has the BS_GROUPBOX style, otherwise it has the BS_OWNERDRAW style.


ScrollableText Control

The individual buttons are created with the "BUTTON" class.

It has the BS_RADIOBUTTON, WS_CHILD, WS_GROUP, WS_TABSTOP, WS_EX_CONTROLPARENT and BS_MULTILINE styles.

This control displays a long string of text that cannot fit entirely on the page. A common application for this control is displaying the license agreement.

Note that the string of text used with this control cannot contain an embedded property. To display text with embedded properties use instead the Text Control.

Control Attributes

You can use the following attributes with this control. To change the value of an attribute using an event, subscribe the control to a ControlEvent in the EventMapping table and list the attribute's identifier in the Attribute column. Enter the Identifier of the ControlEvent in the Event column.

Attribute identifier | Hexadecimal bit | Description
Position |  | Position of control in the dialog box. Enter the control's width, height, and coordinates of the control's left corner into the Width, Height, X, and Y columns of the Control table or BBControl table. Use pixels for units of length and distance.
Text |  | Text displayed by the control. Enter the RTF text string into the Text column of the Control table.
Visible | 0x00000000 0x00000001 | Hidden control. Visible control. To make the control visible or hidden on its creation, include this bit in the bit word of the Attributes column in the Control table or BBControl table. You can also hide or show a control by using the ControlCondition table.
Enabled | 0x00000000 0x00000002 | Control in a disabled state. Control in an enabled state. Include this bit the bit word in the Attributes column of the Control or BBControl tables to enable the control on creation. You can also enable or disable a control by using the ControlCondition table.
Sunken | 0x00000000 0x00000004 | Display the default visual style. Display the control with a sunken, 3D, look. Include these bits in the bit word in the Attributes column of the Control table.
RTLRO | 0x00000000 0x00000020 | Text in the control is displayed in a Left-To-Right-Reading-Order. Text in the control is displayed in a Right-To-Left-Reading-Order.
RightAligned | 0x00000000 0x00000040 | Text in the control is aligned on the left. Text in the control is aligned on the right.
LeftScroll | 0x00000000 0x00000080 | The scroll bar is located on the right side of the control. The scroll bar is located on the left side of the control.
BiDi | 0x000000E0 | Set this value for a combination of the RTLRO, RightAligned, and LeftScroll attributes.

Remarks

The control is created using the "RICHEDIT" class with the ES_MULTILINE, WS_VSCROLL, ES_READONLY, WS_TABSTOP, ES_AUTOVSCROLL, WS_CHILD, WS_GROUP, and ES_NOOLEDRAGDROP styles.


SelectionTree Control

This control enables a user to change the selection state of features listed in the Feature Table. The control is associated with a string valued property that the user can set by a Browse Dialog. You can associate the control with a property by entering the property's name in the Property column of the Control table.

The SelectionTree control publishes the following ControlEvents.

Control event | Description
SelectionAction | Publish string from the UIText table describing highlighted item.
SelectionBrowse | Spawn a browse dialog used to modify path of highlighted item.
SelectionDescription | Publish string from the Feature table describing highlighted item.
SelectionIcon | Publish the handle to the icon for the highlighted item.
SelectionNoItems | Delete the descriptive text or disable the buttons of an obsolete item.
SelectionPath | Publish the path for the highlighted item.
SelectionPathOn | Publishes whether or not there is a selection path associated with the currently selected feature.
SelectionSize | Publish the size of the highlighted item.

The contents of the Text field of the Control table is never displayed by the SelectionTree control. Instead this field specifes the style of text to be displayed by the control and contains a description of the control used by screen review utilities. To set the font and font style of the text displayed by the control, begin the Text column of the Control table with {\style}, where style is an identifier listed in the TextStyle column of the TextStyle table. Use {&style} to apply the base font and font style. The information following this is read by screen review utilities as the description of the control. See Accessibility.

Control Attributes

You can use the following attributes with this control. To change the value of an attribute using an event, subscribe the control to a ControlEvent in the EventMapping table and list the attribute's identifier in the Attribute column. Enter the Identifier of the ControlEvent in the Event column.

Attribute identifier | Hexadecimal bit | Description
IndirectPropertyName |  | This is the name of an indirect property associated with the control. If the Indirect attribute bit is set, the control displays or changes the value of the property having this name. If the Indirect attribute bit is set, this name is also the value of the property listed in the Property column of the Control table.
Position |  | Position of control in the dialog box. Enter the control's width, height, and coordinates of the control's left corner into the Width, Height, X, and Y columns of the Control table. Use pixels for units of length and distance.
PropertyName |  | This is the name of the property associated with this control. If the Indirect attribute bit is not set, the control displays or changes the value of the property having this name. This attribute is specified in the Property column of the Control table.
PropertyValue |  | Current value of the property displayed or changed by this control. If the Indirect attribute bit is not set, this is the value of PropertyName. If the Indirect attribute bit is set, this is the value of IndirectPropertyName. If the attribute changes, the control reflects the new value.
Text |  | To display text in screen readers, enter the text into the Text column of the Control table. See Accessibility.
Visible | 0x00000000 0x00000001 | Hidden control. Visible control. Include this bit in the bit word of the Attributes column in the Control table to make the control visible or hidden upon its creation. You can also hide or show a control by using the ControlCondition table.
Enabled | 0x00000000 0x00000002 | Control in a disabled state. Control in an enabled state. Include this bit in the bit word in the Attributes column of the Control to enable the control on creation. You can also enable or disable a control by using the ControlCondition table.
Sunken | 0x00000000 0x00000004 | Display the default visual style. Display the control with a sunken, 3D, look. Include these bits in the bit word in the Attributes column of the Control table.
Indirect | 0x00000000 0x00000008 | The control displays or changes the value of the property in the Property column of the Control table. The control displays or changes the value of the property that has the Identifier listed in the Property column of the Control table. Determines if the property associated with this control is referenced indirectly.
RTLRO | 0x00000000 0x00000020 | Text in the control is displayed in a Left-To-Right-Reading-Order. Text in the control is displayed in a Right-To-Left-Reading-Order.
RightAligned | 0x00000000 0x00000040 | Text in the control is aligned on the left. Text in the control is aligned on the right.
LeftScroll | 0x00000000 0x00000080 | The scroll bar is located on the right side of the control. The scroll bar is located on the left side of the control.
BiDi | 0x000000E0 | Set this value for a combination of the RTLRO, RightAligned, and LeftScroll attributes.

Remarks

This control is created with the WC_TREEVIEW class and the WS_BORDER, TVS_HASLINES, TVS_HASBUTTONS, TVS_LINESATROOT, TVS_DISABLEDRAGDROP, TVS_SHOWSELALWAYS, WS_CHILD, WS_TABSTOP, WS_GROUP styles.

The selection tree is only populated if the CostInitialize action and CostFinalize action have been called.

The following strings in the UIText table are related to this control.

AbsentPath
The path displayed for an item in the absent state.

The following six strings are used to display the number of children selected and the size associated with the highlighted item.

SelChildCostPos
SelChildCostNeg
SelParentCostPosPos
SelParentCostPosNeg
SelParentCostNegPos
SelParentCostNegNeg

The following strings are used to display the available selection options for an item in a popup menu.

MenuAbsent
MenuLocal
MenuCD
MenuNetwork
MenuAllLocal
MenuAllCD
MenuAllNetwork

The following strings are used to explain the present selection in the SelectionDescription control event.

SelAbsentAbsent
SelAbsentLocal
SelAbsentCD
SelAbsentNetwork
SelLocalAbsent
SelLocalLocal
SelLocalCD
SelLocalNetwork
SelCDAbsent
SelNetworkAbsent
SelCDLocal
SelNetworkLocal
SelCDCD
SelNetworkNetwork

The following four localized strings are used in formatting the size of a file.

Bytes
KB
MB
GB


Text Control

This control displays static text. The text may use a predefined style.

Control Attributes

You can use the following attributes with this control. To change the value of an attribute using an event, subscribe the control to a ControlEvent in the EventMapping table and list the attribute's identifier in the Attribute column. Enter the Identifier of the ControlEvent in the Event column.

Attribute identifier Hexadecimal bit Description
Position Position of control in the dialog box.

Enter the control's width, height, and coordinates of the control's left corner into the Width, Height, X, and Y columns of the Control table or BBControl table. Use pixels for units of length and distance.
Text Text displayed by the control.

To set the font and font style of a text string, prefix the string of characters to be displayed with {\style}. Where style is an identifier listed in the TextStyle column of the TextStyle table. Use {&style} to apply the base font and font style.
TimeRemaining This attribute enables a Text control to display the approximate number of minutes and seconds remaining for an installation.

Subscribe the Text control to the TimeRemaining ControlEvent in the Eventmapping table and enter TimeRemaining into the Attribute column.

The installer publishes a record containing one integer representing the number of seconds remaining in the installation. Include a row in the UIText table with TimeRemaining in the Key column. Enter a formatted text string into the Text column authored to display minutes and seconds. Format this string as described for MsiFormatRecord.
Visible 0x00000000

0x00000001

 Hidden control.

Visible control.

Include this bit in the bit word of the Attributes column in the Control table or BBControl table.to make the control visible or hidden upon its creation.

You can also hide or show a control by using the ControlCondition table.
Enabled 0x00000000

0x00000002

 Control in a disabled state.

Control in an enabled state.

Include this bit in the bit word in the Attributes column of the Control or BBControl tables to enable the control on creation.

You can also enable or disable a control by using the ControlCondition table.
Sunken 0x00000000

0x00000004

 Display the default visual style.

Display the control with a sunken, 3D, look.

Include these bits in the bit word in the Attributes column of the Control table.
RTLRO 0x00000000

0x00000020

 Text in the control is displayed in a Left-To-Right-Reading-Order.

Text in the control is displayed in a Right-To-Left-Reading-Order.
RightAligned 0x00000000

0x00000040

 Text in the control is aligned on the left.

Text in the control is aligned on the right.
Transparent 0x00000000

0x00010000

 Opaque control.

Background shows through control. The control has the WS_EX_TRANSPARENT style.

Include this bit the bit word in the Attributes column of the Control or BBControl tables.
NoPrefix 0x00000000

0x00020000

 Use & in a text string to display the next character as underscored.

The character & in a string is displayed as itself.

Include this bit in the bit word in the Attributes column of the Control or BBControl tables.
NoWrap 0x00000000

0x00040000

 Text wraps.

Text is displayed on a single line. If the text extends beyond the control's margins, it is clipped and an ellipsis ("...") is inserted.

Include this bit in the bit word in the Attributes column of the Control or BBControl tables.
UsersLanguage 0x00000000

0x00100000

 Fonts created in the database codepage.

Fonts created in the user's default UI codepage.
FormatSize Control Attribute 0x00000000

0x00080000

 Formatted as text.

If this bit is set the control attempts to format the displayed text as a number representing a count of bytes. For proper formatting, the control's text must be set to a string representing a number expressed in units of 512 bytes. The displayed value will then be formatted in terms of kilobytes (KB), megabytes (MB), or gigabytes (GB), and displayed with the appropriate string representing the units.

Remarks

The control is created with the "STATIC" class and with the SS_LEFT, WS_CHILD, WS_GROUP styles.


VolumeCostList Control

This control presents information about the cost associated with the selection on the different volumes. The control shows all the volumes involved in the current installation plus all volumes that are of the types specified in the attribute bits. If the required disk space exceeds the amount available on some drive, the volume is highlighted in the table. Clicking on a column header sorts the volumes according to the chosen column.

The following strings are used for the column headings in the control and must be specified in the UIText table.

VolumeCostAvailable
VolumeCostDifference
VolumeCostRequired
VolumeCostSize
VolumeCostVolume

The following four localized strings are used in formatting the size of a file.

Bytes
KB
MB
GB

Authors can set the column widths in the VolumeCostList by control by appending column widths after any font specifications. Column widths are entered as a series of positive integers enclosed in curly braces. Empty curly braces or {0} hides the column. A negative number or a string that cannot be converted into a positive integer is an invalid column width. When an invalid column width is encountered in the series, the remaining columns are hidden. A maximum of 5 column widths can be specified.

The contents of the Text field of the Control table is never displayed by the VolumeCostList control. Instead this field specifes the style of text to be displayed by the control and contains a description of the control used by screen review utilities. To set the font and font style of the text displayed by the control, begin the Text column of the Control table with {\style}, where style is an identifier listed in the TextStyle column of the TextStyle table. Use {&style} to apply the base font and font style. The information following this is read by screen review utilities as the description of the control. See Accessibility.

Note that the installer does not update the content of the VolumeCostControl when a user enters a different path into a PathEdit control, a Browse dialog, DirectoryList control, or DirectoryCombo control because there is no property associated with the VolumeCostControl.

Control Attributes

You can use the following attributes with this control. To change the value of an attribute using an event, subscribe the control to a ControlEvent in the EventMapping table and list the attribute's identifier in the Attribute column. Enter the Identifier of the ControlEvent in the Event column.

Attribute identifier | Hexadecimal bit | Description
Position Position of control in the dialog box.

Enter the control's width, height, and coordinates of the control's left corner into the Width, Height, X, and Y columns of the Control table. Use pixels for units of length and distance.
Text To display text in screen readers, enter the text into the Text column of the Control table. See Accessibility.

To set the column widths in the VolumeCostList control, append the column widths after to any font specifications. Column widths are entered as a series of positive integers enclosed in curly braces. Empty curly braces or {0} hides the column. A negative number or a string that cannot be converted into a positive integer is an invalid column width. When an invalid column width is encountered in the series, the remaining columns are hidden. A maximum of five column widths can be specified.
Visible 0x00000000

0x00000001

 Hidden control.

Visible control.

Include this bit in the bit word of the Attributes column in the Control table to make the control visible or hidden upon its creation.

You can also hide or show a control by using the ControlCondition table.
Enabled 0x00000000

0x00000002

 Control in a disabled state.

Control in an enabled state.

Include this bit in the bit word in the Attributes column of the Control to enable the control on creation.

You can also enable or disable a control by using the ControlCondition table.
Sunken 0x00000000

0x00000004

 Display the default visual style.

Display the control with a sunken, 3D, look.

Include these bits in the bit word in the Attributes column of the Control table.
RTLRO 0x00000000

0x00000020

 Text in the control is displayed in a Left-To-Right-Reading-Order.

Text in the control is displayed in a Right-To-Left-Reading-Order.
RightAligned 0x00000000

0x00000040

 Text in the control is aligned on the left.

Text in the control is aligned on the right.
LeftScroll 0x00000000

0x00000080

 The scroll bar is located on the right side of the control.

The scroll bar is located on the left side of the control.

BiDi | 0x000000E0 | Set this value for a combination of the RTLRO, RightAligned, and LeftScroll attributes.
RemovableVolume 0x00010000 Control lists removable drives.

Include in the bit word in the Attributes column of the Control table.
FixedVolume 0x00020000 Control lists fixed internal hard drives.

Include in the bit word in the Attributes column of the Control table.
RemoteVolume 0x00040000 Control lists remote volumes.

Include in the bit word in the Attributes column of the Control table.
CDROMVolume 0x00080000 Control lists CD-ROM volumes.

Include in the bit word in the Attributes column of the Control table.
RAMDiskVolume 0x00100000 Control lists RAM disks.

Include in the bit word in the Attributes column of the Control table..
FloppyVolume 0x00200000 Control lists floppy drives.

Include in the bit word in the Attributes column of the Control table.
ControlShowRollbackCost 0x00000000

0x00400000

 If PROMPTROLLBACKCOST = P, and this attribute is not set, the rollback backup files are not included in the cost displayed by the VolumeCostList Control.

If PROMPTROLLBACKCOST = P, and this attribute is set, the rollback backup files are included in the cost displayed by the VolumeCostList Control.

This control attribute is ignored if PROMPTROLLBACKCOST = D or F. If PROMPTROLLBACKCOST = F, the cost of rollback the backup files is included. If PROMPTROLLBACKCOST = D, or DISABLEROLLBACK =1, the cost of the rollback backup files is not included.

Remarks

This control is created with the WC_LISTVIEW class and the LVS_REPORT, WS_VSCROLL, WS_HSCROLL, LVS_SHAREIMAGELISTS, LVS_AUTOARRANGE, LVS_SINGLESEL, WS_BORDER, WS_CHILD, WS_TABSTOP, WS_GROUP styles.


VolumeSelectCombo Control

This control enables the user to select a volume from an alphabetical list of volumes. The types of volumes that are displayed in the list are specified using bits associated with the RemovableVolume, FixedVolume, RemoteVolume, CDROMVolume, RAMDiskVolume, and FloppyVolume control attributes.

You can associate this control with a property by entering the property's name in the Property column of the Control table.

Control Attributes

You can use the following attributes with this control. To change the value of an attribute using an event, subscribe the control to a ControlEvent in the EventMapping table and list the attribute's identifier in the Attribute column. Enter the Identifier of the ControlEvent in the Event column.

Attribute identifier | Hexadecimal bit | Description
IndirectPropertyName |  | This is the name of an indirect property associated with the control. If the Indirect attribute bit is set, the control displays or changes the value of the property having this name. If the Indirect attribute bit is set, this name is also the value of the property listed in the Property column of the Control table.
Position |  | Position of control in the dialog box. Enter the control's width, height, and coordinates of the control's left corner into the Width, Height, X, and Y columns of the Control table. Use pixels for units of length and distance.
PropertyName |  | This is the name of the property associated with this control. If the Indirect attribute bit is not set, the control displays or changes the value of the property having this name. This attribute is specified in the Property column of the Control table.
PropertyValue |  | Current value of the property displayed or changed by this control. If the Indirect attribute bit is not set, this is the value of PropertyName. If the Indirect attribute bit is set, this is the value of IndirectPropertyName. If the attribute changes, the control reflects the new value.
Text |  | To set the font and font style of the property contents displayed in the edit field, enter {\style} into the Text column of the Control table. Where style is an identifier listed in the TextStyle column of the TextStyle table. Use {&style} to apply the base font and font style.
Visible | 0x00000000 0x00000001 | Hidden control. Visible control. Include this bit in the bit word of the Attributes column in the Control table to make the control visible or hidden upon its creation. You can also hide or show a control by using the ControlCondition table.
Enabled | 0x00000000 0x00000002 | Control in a disabled state. Control in an enabled state. Include this bit in the bit word in the Attributes column of the Control to enable the control on creation. You can also enable or disable a control by using the ControlCondition table.
Sunken | 0x00000000 0x00000004 | Display the default visual style. Display the control with a sunken, 3D, look. Include these bits in the bit word in the Attributes column of the Control table.
Indirect | 0x00000000 0x00000008 | The control displays or changes the value of the property in the Property column of the Control table. The control displays or changes the value of the property that has the Identifier listed in the Property column of the Control table. Determines if the property associated with this control is referenced indirectly.
RTLRO | 0x00000000 0x00000020 | Text in the control is displayed in a Left-To-Right-Reading-Order. Text in the control is displayed in a Right-To-Left-Reading-Order.
RightAligned | 0x00000000 0x00000040 | Text in the control is aligned on the left. Text in the control is aligned on the right.
LeftScroll | 0x00000000 0x00000080 | The scroll bar is located on the right side of the control. The scroll bar is located on the left side of the control.
BiDi | 0x000000E0 | Set this value for a combination of the RTLRO, RightAligned, and LeftScroll attributes.
RemovableVolume | 0x00010000 | Control lists removable drives. Include in the bit word in the Attributes column of the Control table.
FixedVolume | 0x00020000 | Control lists fixed internal hard drives. Include in the bit word in the Attributes column of the Control table.
RemoteVolume | 0x00040000 | Control lists remote volumes. Include in the bit word in the Attributes column of the Control table.
CDROMVolume | 0x00080000 | Control lists CD-ROM volumes. Include in the bit word in the Attributes column of the Control table.
RAMDiskVolume | 0x00100000 | Control lists RAM disks. Include in the bit word in the Attributes column of the Control table..
FloppyVolume | 0x00200000 | Control lists floppy drives. Include in the bit word in the Attributes column of the Control table.

Remarks

The control is created as a"COMBOBOX" with the CBS_DROPDOWNLIST, CBS_OWNERDRAWFIXED, CBS_HASSTRINGS, WS_VSCROLL, WS_CHILD, WS_GROUP, WS_TABSTOP and CBS_SORT styles.

For compatibility with screenreaders, when authoring a dialog with an VolumeSelectCombo control as the first active control, you must make the text field belonging to the edit field the first active control in the Dialog Table. Since the static text cannot take focus, when the dialog is created the edit field will have the focus initially as intended. Doing this ensures that screenreaders show the correct information.


Control Attributes

For information on control attributes, see the link to the particular control that you need to create in Controls as well as the links to particular control attributes in the following lists.

The following are the methods generally used for specifying the attributes of a control.

  • Use the ControlCondition table to disable, enable, hide, or show a control according to the value of a property or conditional statement. You can also use this table to override the default control specified in the Dialog table.
  • Subscribe the control to a ControlEvent in the EventMapping table. Enter the attribute's identifier in the Attribute column and the ControlEvent's identifier in the Event column of this table.
  • Set the control attribute bit flags for the control in the Attribute column of the Control table. This sets the attributes upon the creation of the control.

Some attributes cannot be set for every control or be specified by all of the above methods. See the particular control and attribute topics for details.

The initial values of some control attributes can be set with bits in the Control table.

Attribute | Decimal | Hexadecimal | Constant
BiDi | 224 | 0x000000E0 | msidbControlAttributesBiDi
Enabled | 2 | 0x00000002 | msidbControlAttributesEnabled
Indirect | 8 | 0x00000008 | msidbControlAttributesIndirect
Integer Control | 16 | 0x00000010 | msidbControlAttributesInteger
LeftScroll | 128 | 0x00000080 | msidbControlAttributesLeftScroll
RightAligned | 64 | 0x00000040 | msidbControlAttributesRightAligned
RTLRO | 32 | 0x00000020 | msidbControlAttributesRTLRO
Sunken | 4 | 0x00000004 | msidbControlAttributesSunken
Visible | 1 | 0x00000001 | msidbControlAttributesVisible

These attributes of text controls are set with bits.

Attribute | Decimal | Hexadecimal | Constant
FormatSize | 524288 | 0x00080000 | msidbControlAttributesFormatSize
NoPrefix | 131072 | 0x00020000 | msidbControlAttributesNoPrefix
NoWrap | 262144 | 0x00040000 | msidbControlAttributesNoWrap
Password | 2097152 | 0x00200000 | msidbControlAttributesPasswordInput
Transparent | 65536 | 0x00010000 | msidbControlAttributesTransparent
UsersLanguage | 1048576 | 0x00100000 | msidbControlAttributesUsersLanguage

This attribute of the progress bar control is set with a bit.

Attribute | Decimal | Hexadecimal | Constant
Progress95 | 65536 | 0x00010000 | msidbControlAttributesProgress95

These attributes of volume and directory select combo controls are set with bits.

Attribute | Decimal | Hexadecimal | Constant
CDROMVolume | 524288 | 0x00080000 | msidbControlAttributesCDROMVolume
FixedVolume | 131072 | 0x00020000 | msidbControlAttributesFixedVolume
FloppyVolume | 2097152 | 0x00200000 | msidbControlAttributesFloppyVolume
RAMDiskVolume | 1048576 | 0x00100000 | msidbControlAttributesRAMDiskVolume
RemoteVolume | 262144 | 0x00040000 | msidbControlAttributesRemoteVolume
RemovableVolume | 65536 | 0x00010000 | msidbControlAttributesRemovableVolume

These attributes of list box and combo box controls are set with bits.

Attribute | Decimal | Hexadecimal | Constant
ComboList Control | 131072 | 0x00020000 | msidbControlAttributesComboList
Sorted Control | 65536 | 0x00010000 | msidbControlAttributesSorted

This attribute of the edit control is set with a bit.

Attribute | Decimal | Hexadecimal | Constant
MultiLine | 65536 | 0x00010000 | msidbControlAttributesMultiline

These attributes of picture button controls are set with bits:

Attribute | Decimal | Hexadecimal | Constant
Bitmap | 262144 | 0x00040000 | msidbControlAttributesBitmap
FixedSize | 1048576 | 0x00100000 | msidbControlAttributesFixedSize
Icon | 524288 | 0x00080000 | msidbControlAttributesIcon
IconSize16 | 2097152 | 0x00200000 | msidbControlAttributesIconSize16
IconSize32 | 4194304 | 0x00400000 | msidbControlAttributesIconSize32
IconSize48 | 6291456 | 0x00600000 | msidbControlAttributesIconSize48
ImageHandle | 65536 | 0x00010000 | msidbControlAttributesImageHandle
PushLike Control | 131072 | 0x00020000 | msidbControlAttributesPushLike

This attribute of radio button controls is set with a bit.

Attribute | Decimal | Hexadecimal | Constant
HasBorder | 16777216 | 0x01000000 | msidbControlAttributesHasBorder

This attribute of VolumeCostList Control is set with a bit.

Attribute | Decimal | Hexadecimal | Constant
ControlShowRollbackCost | 4194304 | 0x00400000 | msidbControlShowRollbackCost

The following control attributes are not set with bits. These attributes are authored into the user interface tables or are set using Control Events.

BillboardName
IndirectPropertyName
Position
Progress Control
PropertyName
PropertyValue
Text Control
TimeRemaining

See Adding Controls and Text.


BiDi Control Attribute

This is a combination of the right to left reading order RTLRO, the RightAligned, and LeftScroll attributes.

Valid Controls

ScrollableText
VolumeCostList
ComboBox
DirectoryList
DirectoryCombo
Edit
ListBox
ListView
SelectionTree
VolumeSelectCombo

Value

Decimal | Hexadecimal | Constant
224 | 0x000000E0 | msidbControlAttributesBiDi

Remarks

To set this attribute on a control, include the BiDi bit in the Attributes column of the control's record in the Control table.

See Control Attributes and the control you need to create under Controls.


BillboardName Control Attribute

This attribute returns the name of the currently running billboard, or sets and displays a billboard by name. This attribute is used in preview mode.

Valid Controls

Billboard

Associated Bit Flags

None.

Remarks

See Control Attributes and the control you need to create under Controls.


Bitmap Control Attribute

If the Bitmap Control bit is set, the text in the control is replaced by a bitmap image. The Text column in the Control table is a foreign key into the Binary table.

If this bit is not set, the text in the control is specified in the Text column of the Control table.

Valid Controls

CheckBox
PushButton
RadioButtonGroup

Value

Decimal | Hexadecimal | Constant
262144 | 0x00040000 | msidbControlAttributesBitmap

Remarks

To set this attribute on a control, include the Bitmap bit in the Attributes column of the control's record in the Control table.

The Text column in the Control table is used as a foreign key to the Binary table, therefore the control cannot contain both an icon image and text.

Do not set both the Icon and Bitmap bits.

See Control Attributes and the control you need to create under Controls.


CDROMVolume Control Attribute

If the CDROMVolume Control bit is set, the control shows all the volumes in the current installation plus all the CD-ROM volumes.

If this bit is not set, the control shows all the volumes in the current installation.

Valid Controls

DirectoryCombo
VolumeCostList
VolumeSelectCombo

Value

Decimal | Hexadecimal | Constant
524288 | 0x00080000 | msidbControlAttributesCDROMVolume

Remarks

To set this attribute on a control, include the CDROMVolume bit in the Attributes column of the control's record in the Control table.

See Control Attributes and the control you need to create under Controls.


ComboList Control Attribute

If the ComboList Control bit is set on a combo box, the edit field is replaced by a static text field. This prevents a user from entering a new value and requires the user to choose only one of the predefined values.

If this bit is not set, the combo box has an edit field.

Valid Controls

ComboBox

Value

Decimal | Hexadecimal | Description
131072 | 0x00020000 | msidbControlAttributesComboList

Remarks

To set this attribute on a control, include the ComboList bit in the Attributes column of the control's record in the Control table.

See Control Attributes and the control you need to create under Controls.


ControlShowRollbackCost Control Attribute

This attribute specifies whether or not the rollback backup files are included in the costs displayed by the VolumeCostList control.

If this bit is set and PROMPTROLLBACKCOST property = P, the rollback backup files are included in the cost displayed by the VolumeCostList Control.

If this bit is not set and PROMPTROLLBACKCOST property = P, the rollback backup files are not included in the cost displayed by the VolumeCostList Control.

Valid Controls

VolumeCostList

Value

Decimal | Hexadecimal | Constant
4194304 | 0x00400000 | msidbControlShowRollbackCost

Remarks

This control attribute is ignored if PROMPTROLLBACKCOST = D or F.

If PROMPTROLLBACKCOST = F, the cost of the rollback backup files is included.

If PROMPTROLLBACKCOST = D, or DISABLEROLLBACK property =1, the cost of the rollback backup files is not included.


Enabled Control Attribute

This attribute specifies if the given control is enabled or disabled. Most controls appear gray when disabled.

If this bit is set, the control is created as enabled.

If this bit is not set, the control is created as disabled.

Valid Controls

All controls. The appearance of some controls that are not associated with a property, such as Bitmaps and Icons, are unaffected by setting this attribute.

Value

Decimal | Hexadecimal | Constant
2 | 0x00000002 | msidbControlAttributesEnabled

Remarks

You can also use the ControlCondition table to disable or enable a control according to the value of a property or conditional statement.

You can also enable or disable a control by subscribing the control to a control event. Enter the attribute's identifier in the Attribute column and the event's identifier in the Event column of the EventMapping table.

See Control Attributes and the control you need to create under Controls.


FixedSize Control Attribute

If the FixedSize Control bit is set, the picture is cropped or centered in the control without changing its shape or size.

If this bit is not set the picture is stretched to fit the control.

Valid Controls

Bitmap
CheckBox
Icon
PushButton
RadioButtonGroup

Value

Decimal | Hexadecimal | Constant
1048576 | 0x00100000 | msidbControlAttributesFixedSize

Remarks

To set this attribute on a control, include the FixedSize bit in the Attributes column of the control's record in the Control table.

Setting the FixedSize bit has no effect on a CheckBox, PushButton, or RadioButtonGroup if neither the Bitmap or the Icon have been set.

Setting the FixedSize bit has no effect on an Icon control, or a PushButton associated with an icon, if the IconSize bits is not set.

See Control Attributes and the control you need to create under Controls.


FixedVolume Control Attribute

If the FixedVolume Control bit is set, the control shows all the volumes involved in the current installation plus all the fixed internal hard drives.

If this bit is not set, the control lists the volumes in current installation.

Valid Controls

DirectoryCombo
VolumeCostList
VolumeSelectCombo

Values

Decimal | Hexadecimal | Constant
131072 | 0x00020000 | msidbControlAttributesFixedVolume

Remarks

To set this attribute on a control, include the FixedVolume bit in the Attributes column of the control's record in the Control table.

See Control Attributes and the control you need to create under Controls.


FloppyVolume Control Attribute

If the FloppyVolume Control bit is set, the control shows all the volumes involved in the current installation plus all the floppy volumes.

If this bit is not set, the control lists volumes in current installation.

Valid Controls

DirectoryCombo
VolumeCostList
VolumeSelectCombo

Value

Decimal | Hexadecimal | Constant
2097152 | 0x00200000 | msidbControlAttributesFloppyVolume

Remarks

To set this attribute on a control, include the FloppyVolume bit in the Attributes column of the control's record in the Control table.

See Control Attributes and the control you need to create under Controls.


FormatSize Control Attribute

If this bit is set for a static text control, the control will automatically attempt to format the displayed text as a number representing a count of bytes. For proper formatting, the control's text must be set to a string representing a number expressed in units of 512 bytes. The displayed value will then be formatted in terms of kilobytes (KB), megabytes (MB), or gigabytes (GB), and displayed with the appropriate string representing the units.

Numerical value of original text: | Unit string used:
less than 20480 | KB
less than 20971520 | MB
less than 10737418240 | GB

Valid Controls:

Text control

Values

Decimal | Hexadecimal | Control
524288 | 0x00080000 | msidbControlAttributesFormatSize

Remarks

To set this attribute on a control, include the FormatSize bits in the Attributes column of the control's record in the Control table.

Control Table to be set to the PrimaryVolumeSpaceRequired property. The installer resolves this property at run time to the total number of bytes required for the installation in units of 512. For the purposes of this example, assume the property resolves to the value 18,336,768. The value for the PrimaryVolumeSpaceRequired property would be set to 18,336,768 divided by 512, or 35814. The number displayed in the control would be 17MB.

The numerical values of the original text are given in units of 512. In the table above, the string 20480 corresponds to the KB string because 20480 times 512 yields a result of 10,485,760 bytes or 10,240 KB.

The unit strings listed in the previous table actually refer to keys in the UIText table, where the text of the unit string is defined.

The positioning of the unit string is controlled by the LeftUnit property. If the LeftUnit property is defined to be any value, the unit string appears before the numerical value.

If anything other than numerical characters appears in the text associated with the control, the displayed value is undefined.

See Control Attributes and the control you need to create under Controls.


HasBorder Control Attribute

If this bit is set, the RadioButtonGroup has text and a border displayed around it.

If the style bit is not set, the border is not displayed and no text is displayed on the group.

Valid Controls

RadioButtonGroup

Valid

Decimal | Hexadecimal | Constant
16777216 | 0x01000000 | msidbControlAttributesHasBorder

Remarks

To set this attribute on a control, include the HasBorder bits in the Attributes column of the control's record in the Control table.

See Control Attributes and the control you need to create under Controls.


Icon Control Attribute

If this bit is set, text is replaced by an icon image and the Text column in the Control table is a foreign key into the Binary table.

If this bit is not set, text in the control is specified in the Text column of the Control table.

Valid Controls

CheckBox
PushButton
RadioButtonGroup

Value

Decimal | Hexadecimal | Constant
5242288 | 0x00080000 | msidbControlAttributesIcon

Remarks

To set this attribute on a control, include the Icon bits in the Attributes column of the control's record in the Control table.

The Text column in the Control table is used as a foreign key to the Binary table, therefore the control cannot contain both an icon image and text.

Do not set both the Icon and Bitmap bits.

See Control Attributes and the control you need to create under Controls.


IconSize Control Attribute

An icon file can hold several different sizes of the same icon image. These bits specify which size of the icon image to load. If none of the bits are set, the first image is loaded. If only msidbControlAttributesIconSize16 is set, the first 16x16 image is loaded. If only the msidbControlAttributesIconSize32 is set, the first 32x32 image is loaded. If msidbControlAttributesIconSize48 is set, the first 48x48 image is loaded.

Valid Controls

CheckBox
Icon
PushButton
RadioButtonGroup

Value

Decimal | Hexadecimal | Description
2097152 | 0x00200000 | msidbControlAttributesIconSize16
4194304 | 0x00400000 | msidbControlAttributesIconSize32
6291456 | 0x00600000 | msidbControlAttributesIconSize48

Remarks

To set this attribute on a control, include the IconSize bits in the Attributes column of the control's record in the Control table.

If the FixedSize bit is not set, the loaded image is shrunk or stretched to fit the icon control. If the FixedSize bit is set, and the loaded image is smaller than the icon control, the picture is displayed centered inside the control. If the FixedSize bit is set, and the loaded image is larger than the icon control, the picture is shrunk to fit the control.

See Control Attributes and the control you need to create under Controls.


ImageHandle Control Attribute

The installer uses the ImageHandle control attribute to determine whether the Text control attribute is an image specified in the Binary table or the handle to an image loaded in memory at run-time. See the links of the particular controls listed in the following as Valid Controls.

The Text Control Attribute and ImageHandle Control Attribute must be used together in the Icon and Bitmap controls. For information on how to use this attribute in those controls, see Icon Control and Bitmap Control.

A typical use of the control is to display all the running applications. This is commonly done with an action that finds all the running applications and puts their names and icons into the ListView Table

The handle to the image, in string format, must be specified in the Text column of the Control table. Because the value of the handle cannot be authored into the table, it must be set by an action performed prior to creating the control.

Even if this bit is set, the other style bits governing the size and stretching of the image are still observed. For example, if an action puts a handle of an image in the table, but other style bits describe a different size, the image is shrunk or stretched to size specified by the bits.

Valid Controls

Bitmap
CheckBox
Icon
PushButton
RadioButtonGroup

Value

Decimal | Hexadecimal | Constant
65536 | 0x00010000 | msidbControlAttributesImageHandle

Remarks

See Control Attributes and the control you need to create under Controls.


Indirect Control Attribute

The Indirect control attribute specifies whether the value displayed or changed by this control is referenced indirectly.

If this bit is set, the control displays or changes the value of the property that has the Identifier listed in the Property column of the Control table.

If this bit is not set, the control displays or changes the value of the property in the Property column of the Control table.

Valid Controls

All active controls.

Value

Decimal | Hexadecimal | Constant
8 | 0x00000008 | msidbControlAttributesIndirect

Remarks

See Control Attributes and the control you need to create under Controls.


IndirectPropertyName Control Attribute

This attribute is the name of an indirect property associated with the control. If the Indirect bit is set, the control displays or changes the value of the property having this name and this name is the value of the property listed in the Property column of the Control table.

For inert controls this attribute returns Null.

Valid Controls

All active controls.

Associated Bit Flags

None.

Remarks

See Control Attributes and the control you need to create under Controls.


Integer Control Attribute

If this bit is set on a control, the associated property specified in the Property column of the Control table is an integer.

If this bit is not set, the property is a string value.

Valid Controls

CheckBox
ComboBox
Edit
ListBox
RadioButtonGroup

Value

Decimal | Hexadecimal | Constant
16 | 0x00000010 | msidbControlAttributesInteger

Remarks

To set this attribute on a control, include the Integer bit in the Attributes column of the control's record in the Control table.

See Control Attributes and Controls.


LeftScroll Control Attribute

If this bit is set, the scroll bar is located on the left side of the control.

If this bit is not set, the scroll bar is on the right side of the control.

Valid Controls

ScrollableText
VolumeCostList
ComboBox
DirectoryList
DirectoryCombo
Edit
ListBox
ListView
SelectionTree
VolumeSelectCombo

Value

Decimal | Hexadecimal | Constant
128 | 0x00000080 | msidbControlAttributesLeftScroll

Remarks

To set this attribute on a control, include the LeftScroll bit in the Attributes column of the control's record in the Control table.

See Control Attributes and Controls.


MultiLine Control Attribute

If this bit is set on an Edit control, the installer creates a multiple line edit control with a vertical scroll bar.

If this bit is not set, it specifies displaying a normal edit control.

Valid Controls

Edit control.

Values

Decimal | Hexadecimal | Constant
65536 | 0x00010000 | msidbControlAttributesMultiline

Remarks

To set this attribute on a control, include the MultiLine bit in the Attributes column of the control's record in the Control table.

See Control Attributes and Controls.


NoPrefix Control Attribute

If this bit is set on a text control, the occurrence of the character "&" in a text string is displayed as itself.

If this bit is not set, then the character following "&" in the text string is displayed as an underscored character.

Valid Controls

Text

Value

Decimal | Hexadecimal | Constant
131072 | 0x20000 | msidbControlAttributesNoPrefix

Remarks

To set this attribute on a control, include the NoPrefix bit in the Attributes column of the control's record in the Control table.

See Control Attributes and Controls.


NoWrap Control Attribute

If this bit is set the text in the control is displayed on a single line. If the text extends beyond the control's margins it is truncated and an ellipsis ("...") is inserted at the end to indicate the truncation.

If this bit is not set text wraps.

Valid Controls

Text

Value

Decimal | Hexadecimal | Constant
262144 | 0x00040000 | msidbControlAttributesNoWrap

Remarks

To set this attribute on a control, include the NoWrap bit in the Attributes column of the control's record in the Control table.

See Control Attributes and Controls.


Password Control Attribute

This attribute creates an edit control for entering passwords. The control displays each character as an asterisk (*) as they are typed into the control.

Valid Controls

Edit control

Associated Bit Flags

None.

Remarks

See Control Attributes and Controls.

This Edit control attribute is not available with Windows Installer version 1.0.


Position Control Attribute

This attribute determines the position of the control on the dialog. The four fields of the attribute are: left, top, width, and height. Enter the control's width, height, and coordinates of the control's left corner into the Width, Height, X, and Y columns of the Control table. Use pixels for units of length and distance.

Valid Controls

All active controls.

Associated Bit Flags

None.

Remarks

See Control Attributes and the control you need to create under Controls.


Progress95 Control Attribute

If this bit is set on a ProgressBar control, the bar is drawn as a series of small rectangles in Microsoft® Windows® 95-style.

If this bit is not set, the progress indicator bar is drawn as a single continuous rectangle.

Valid Controls

ProgressBar

Value

Decimal | Hexadecimal | Constant
65536 | 0x00010000 | msidbControlAttributesProgress95

Remarks

To set this attribute on a control, include the Progress95 bit in the Attributes column of the control's record in the Control table.

See Control Attributes and the control you need to create under Controls.


Progress Control Attribute

This attribute measures how far the progress indicator bar is filled up. The record contains two integers and a string. The first number is the progress, the second number is the range (the maximal possible number for the progress).

On setting, the integers can be entered as integer fields or strings containing the integers.

If the second number is missing it is assumed to be the default (1024). If the progress is larger than the range then it is changed to be the range. The third field is a string, the name of the action whose progress is displayed.

For related information, see Authoring a Progress Bar Control, and Adding Custom Actions to the ProgressBar.

Valid Controls

ProgressBar

Associated Bit Flags

None.

Remarks

See Control Attributes and the control you need to create under Controls.


PropertyName Control Attribute

This is the name of the property associated with this control. If the Indirect bit is not set, the control displays or changes the value of the property having this name. This attribute is specified in the Property column of the Control table.

This attribute returns Null for inert controls.

Valid Controls

All controls.

Associated Bit Flags

None.

Remarks

See Control Attributes and the control you need to create under Controls.


PropertyValue Control Attribute

This attribute is the present value of the property displayed or changed by this control. If the Indirect bit is not set, this is the value of PropertyName. If the Indirect attribute bit is set, this is the value of IndirectPropertyName. If the attribute changes, the control reflects the new value.

String or Integer depending on the Integer attribute of the control.

Valid Controls

All active controls.

Associated Bit Flags

None.

Remarks

See Control Attributes and the control you need to create under Controls.


PushLike Control Attribute

If this bit is set on a check box or a radio button group, the button is drawn with the appearance of a push button, but its logic stays the same.

If the bit is not set, the controls are drawn in their usual style.

Valid Controls

CheckBox
RadioButtonGroup

Value

Decimal | Hexadecimal | Constant
131072 | 0x00020000 | msidbControlAttributesPushLike

Remarks

To set this attribute on a control, include the PushLike bit in the Attributes column of the control's record in the Control table.

See Control Attributes and Controls.


RAMDiskVolume Control Attribute

If this bit is set, the control shows all the volumes involved in the current installation plus all the RAM disk volumes.

If this bit is not set the control lists volumes in current installation.

Valid Controls

DirectoryCombo
VolumeCostList
VolumeSelectCombo

Value

Decimal | Hexadecimal | Constant
1048567 | 0x00100000 | msidbControlAttributesRAMDiskVolume

Remarks

To set this attribute on a control, include the RAMDiskVolume bit in the Attributes column of the control's record in the Control table.

See Control Attributes and Controls.


RemoteVolume Control Attribute

If this bit is set, the control shows all the volumes involved in the current installation plus all the remote volumes.

If this bit is not set, the control lists volumes in current installation.

Valid Controls

DirectoryCombo
VolumeCostList
VolumeSelectCombo

Value

Decimal | Hexadecimal | Constant
262144 | 0x00040000 | msidbControlAttributesRemoteVolume

Remarks

To set this attribute on a control, include the RemoteVolume bit in the Attributes column of the control's record in the Control table.

See Control Attributes and Controls.


RemovableVolume Control Attribute

If this bit is set, the control shows all the volumes involved in the current installation plus all the removable volumes.

If this bit is not set, the control lists volumes in current installation.

Valid Controls

DirectoryCombo
VolumeCostList
VolumeSelectCombo

Value

Decimal | Hexadecimal | Constant
65536 | 0x00010000 | msidbControlAttributesRemovableVolume

Remarks

To set this attribute on a control, include the RemovableVolume bit in the Attributes column of the control's record in the Control table.

See Control Attributes and Controls.


RightAligned Control Attribute

If this style bit is set, text in the control is aligned to the right.

Valid Controls

GroupBox
ScrollableText
Text
VolumeCostList
CheckBox
ComboBox
DirectoryList
DirectoryCombo
Edit
PathEdit
ListBox
ListView
RadioButtonGroup
SelectionTree
VolumeSelectCombo

Values

Decimal | Hexadecimal | Description
64 | 0x00000040 | msidbControlAttributesRightAligned

Remarks

To set this attribute on a control, include the RightAligned bit in the Attributes column of the control's record in the Control table.

See Control Attributes and Controls.


RTLRO Control Attribute

If this style bit is set the text in the control is displayed in a Right-To-Left-Reading-Order.

Valid Controls

GroupBox
ProgressBar
PushButton
ScrollableText
Text
VolumeCostList
CheckBox
ComboBox
DirectoryList
DirectoryCombo
Edit
PathEdit
ListBox
ListView
RadioButtonGroup
SelectionTree
VolumeSelectCombo

Value

Decimal | Hexadecimal | Constant
32 | 0x00000020 | msidbControlAttributesRTLRO

Remarks

To set this attribute on a control, include the RTLRO bit in the Attributes column of the control's record in the Control table.

See Control Attributes and Controls.


Sorted Control Attribute

If this bit is set, the items listed in the control are displayed in a specified order.

If the bit is not set, items are displayed in alphabetical order.

Valid Controls

ComboBox
ListBox
ListView Control

Value

Decimal | Hexadecimal | Constant
65536 | 0x00010000 | msidbControlAttributesSorted

Remarks

To sort the items in a ComboBox, include the Sorted bit in the Attributes column of the Control table and specify the item order in the Order column of the ComboBox table.

To sort the items in a ListBox, include the Sorted bit in the Attributes column of the Control table and specify the item order in the Order column of the ComboBox table.

To sort the items in a ListView, include the Sorted bit in the Attributes column of the Control table and specify the order of items in the ComboBox table.

See Control Attributes and Controls.


Sunken Control Attribute

If this bit is set, the control is displayed with a sunken, three dimensional look. The effect of this style bit is different on different controls and versions of Windows. On some controls it has no visible effect. If the system does not support the Sunken control attribute, the control is displayed in the default visual style.

If this bit is not set, the control is displayed with the default visual style.

Valid Controls

All controls.

Value

Decimal | Hexadecimal | Constant
4 | 0x00000004 | msidbControlAttributesSunken

Remarks

To set this attribute on a control, include the Sunken bit in the Attributes column of the control's record in the Control table.

See Control Attributes and Controls.


Text Control Attribute

This attribute is the text string displayed in the control. On setting, if the field 0 of the record is not null, the record is formatted using FormatText. If the field 0 is null, the first field of the record defines the text. On getting the value is always returned in the first field. For some controls this text may not be visible. In Windows the accelerator key for a control is defined by placing a "&" in front of the desired character in this string.

Valid Controls

All controls except the Line Control.

Associated Bit Flags

None.

Remarks

See Control Attributes and the control you need to create under Controls.


TimeRemaining Control Attribute

This attribute enables a text control to display the approximate number of minutes and seconds remaining for an installation. A record passed to the text control contains one integer representing the number of seconds remaining. The text control searches the UIText table for a string named TimeRemaining and formats the integer into an appropriate string displaying minutes and seconds.

Valid Controls

Text

Associated Bit Flags

None.

Remarks

See Control Attributes and the control you need to create under Controls.


Transparent Control Attribute

If Transparent Control bit is set on a text control, the control is displayed transparently with the background showing through the control where there are no characters.

If this bit is not set the text control is opaque.

Valid Controls

Text

Value

Decimal | Hexadecimal | Constant
65536 | 0x00010000 | msidbControlAttributesTransparent

Remarks

See Control Attributes and the control you need to create under Controls.


UsersLanguage Control Attribute

If this bit flag is set, fonts are created using the user's default UI code page.

If the bit flag is not set, fonts are created using the database code page.

Valid Controls

Text
ListBox
ComboBox

Value

Decimal | Hexadecimal | Constant
1048576 | 0x00100000 | msidbControlAttributesUsersLanguage

Remarks

This control attribute can be used to display text that the user has entered into an Edit or PathEdit control.

See Control Attributes and Controls.


Visible Control Attribute

If the Visible Control bit is set, the control is visible on the dialog box.

If this bit is not set, the control is hidden on the dialog box.

The visible or hidden state of the Visible control attribute can be later changed by a Control Event.

Valid Controls

All controls.

Value

Decimal | Hexadecimal | Constant
1 | 0x00000001 | msidbControlAttributesVisible

Remarks

You can also use the ControlCondition table to show or hide a control according to the value of a property or conditional statement.

You can also show or hide a control by subscribing the control to a control event. Enter the attribute's identifier in the Attribute column and the event's identifier in the Event column of the EventMapping table.

See Control Attributes and Controls.


Control Events

A ControlEvent specifies an action to be taken by the installer or a change in the attributes of one or more controls in a dialog box. For more information about ControlEvents, see ControlEvent Overview.

The following list provides links to more information about particular ControlEvents:

Control event | Brief description of control event
ActionData | Publishes data on the latest action.
ActionText | Publishes the name of the present action.
AddLocal | Notifies the installer to run features locally.
AddSource | Notifies the installer to run features from source.
CheckExistingTargetPath | Notifies installer to verify that path can be written.
CheckTargetPath | Notifies installer to verify that path is valid.
DirectoryListNew | Notifies DirectoryList control to create new folder.
DirectoryListOpen ControlEvent | Selects directory in the DirectoryList control.
DirectoryListUp | Notifies DirectoryList control to select parent of the present directory.
DoAction | Dialog box notifies installer to execute custom action.
EnableRollback ControlEvent | Used to turn rollback capabilities off and on.
EndDialog | Notifies installer to remove a modal dialog box.
IgnoreChange | Published by the DirectoryList control when a folder is highlighted but not opened.
NewDialog | Notifies installer to change a modal dialog box into another dialog box.
Reinstall | Initiates a reinstall of features.
ReinstallMode | Specifies the validation mode during a reinstall.
Remove | Notifies installer when features are selected for removal.
Reset | Resets all the property values to when the dialog was created.
ScriptInProgress | Displays a string while execution script is compiled.
SelectionAction | Published by SelectionTree to describe an item.
SelectionBrowse | Published by SelectionTree to spawn browse dialog.
SelectionDescription | Publish by SelectionTree to provide string in Description field of Feature Table.
SelectionIcon | Published by SelectionTree to provide icon handle.
SelectionNoItems ControlEvent | Used by SelectionTree to delete text or disable buttons.
SelectionPath | Published by SelectionTree to provide path of item.
SelectionPathOn | Published by SelectionTree to indicate whether there is a path associated with a feature.
SelectionSize | Published by SelectionTree control to provide size of the item.
SetInstallLevel | Installer changes installation level to specified value.
SetProgress | Published by installer to provide installation progress.
SetProperty | Sets a specified property.
SetTargetPath | Notifies installer to check and set a path.
SpawnDialog | Notifies installer to create a child of a modal box.
SpawnWaitDialog | Triggers a specified dialog.
TimeRemaining | Published by installer to provide time remaining in the progress sequence.
ValidateProductID | Sets ProductID to the full Product ID.


ActionData ControlEvent

The installer uses this event to publish data on the latest action.

Published By

This Control Event is published by the installer.

Argument

None.

Action on Subscribers

The subscribers are hidden when a new action starts and they are shown when new action data arrives from the installer.

Typical Use

A Text control on a modeless dialog subscribes to this event using the text attribute to receive the latest data on the current action. Used commonly to display the names of the files copied during file copy.


ActionText ControlEvent

The installer uses this event to publish the name of the present action.

Published By

This ControlEvent is published by the installer.

Argument

None.

Action on Subscribers

The subscribers are shown when a new progress data arrives from the installer.

Typical Use

A Text control on a modeless dialog subscribes to this event using the text attribute to receive the name of the current action.


AddLocal ControlEvent

The this event notifies the installer, while keeping the present dialog running, that a feature or all features are to be run locally.

Published By

This ControlEvent is published by the installer.

Argument

A string, either the name of the feature or "ALL".

Action on Subscribers

None.

Typical Use

A PushButton control on a modal dialog is tied to this event and used to notify the installer without stopping the dialog.


AddSource ControlEvent

This event notifies the installer, while keeping the present dialog running, that a feature or all features are to be run from source.

Published By

This ControlEvent is published by the installer.

Argument

A string, either the name of the feature or "ALL".

Action on Subscribers

None.

Typical Use

A PushButton control on a modal dialog is tied to this event and used to notify the installer without stopping the dialog.


CheckExistingTargetPath ControlEvent

This event notifies the installer that it has to verify that the selected path is writable. If the path is cannot be written, then the event blocks further control events associated with the control.

Published By

This ControlEvent is published by the installer.

Argument

The name of the property containing the path. If the property is indirected, then the property name is enclosed in square brackets.

Action on Subscribers

None.

Typical Use

A PushButton control on a browse dialog is tied to this event in the ControlEvent table to check the selected path before returning to the selection dialog.


CheckTargetPath ControlEvent

This event notifies the installer that it has to verify that the selected path is valid. If the path is not valid, then this event blocks further control events associated with the control.

Published By

This ControlEvent is published by the installer.

Argument

The name of the property containing the path. If the property is indirected, then the property name is enclosed in square brackets.

Action on Subscribers

None.

Typical Use

A PushButton control on a browse dialog is tied to this event in the ControlEvent table to check the selected path before returning to the selection dialog.


IgnoreChange ControlEvent

The IgnoreChange control event is published by the DirectoryList control when a folder is highlighted but not opened in the current directory.

Published By

DirectoryList

Argument

None.

Action on Subscribers

None.

Typical Use

The DirectoryCombo control commonly employs the IgnoreChange control event.


DirectoryListNew ControlEvent

This event notifies the DirectoryList control that a new folder must be created; it creates the new folder, and selects the name field of the folder for editing. The default name of the new folder may be authored in the UIText table. Enter "NewFolder" into the Key column. Enter the value for the default name of the new folder into the Text column. This value must be in the form of a Filename column data type and use the SFN|LFN syntax. If this value is not present in the UIText table or is an invalid value, the installer uses a default value of "Fldr|New Folder." For related information, see Browse Dialog.

Published By

DirectoryList

Argument

None.

Action on Subscribers

None.

Typical Use

A PushButton control on the same modal dialog as the DirectoryList is used to trigger the creation of a new folder.


DirectoryListOpen ControlEvent

This event selects and highlights a directory in the DirectoryList control that the user has chosen to open. For related information, see Browse Dialog.

Published By

DirectoryList

Argument

None.

Action on Subscribers

A selected folder is enabled. If no folder in selected currently, then the subscribers are disabled.

Typical Use

A PushButton control on the same modal dialog as the DirectoryList is used to trigger stepping down in the path.


DirectoryListUp ControlEvent

This event notifies the DirectoryList control that the user wants to select the parent of the present directory. For related information, see Browse Dialog.

Published By

DirectoryList

Argument

None.

Action on Subscribers

The subscribers are disabled if the current directory is a volume and has no parent. Subscribers are otherwise enabled.

Typical Use

A PushButton control on the same modal dialog as the DirectoryList is used to trigger stepping up in the path.


DoAction ControlEvent

A dialog box notifies the installer to execute a custom action.

Note that custom actions launched by the DoAction control event cannot send messages with MsiProcessMessage.

Published By

This ControlEvent is published by the installer.

Argument

A string, the name of the custom action to be executed.

Action on Subscribers

None.

Typical Use

A PushButton control on a dialog is tied to this event in the ControlEvent table to invoke a custom action.


EnableRollback ControlEvent

This control event can be used to turn on or turn off the installer's rollback capabilities.

Published By

This ControlEvent is published by the installer.

Argument

False turns off the installer's rollback capabilities. True turns on the installer's rollback capabilities.

Action on Subscribers

None.

Typical Use

Can be used to turn off rollback capabilities if the installer detects that there is insufficient disk space available to complete the install. For this case, the ControlEvent should be used with the OutOfDiskSpace, OutOfNoRbDiskSpace, and the PROMPTROLLBACKCOST properties.


EndDialog ControlEvent

This event notifies the installer to remove a modal dialog box. In all cases the installer removes the present dialog box.The following table lists the action of the event resulting from different arguments entered into the ControlEvent table.

Argument | Action by the installer
Exit | The wizard sequence is closed and the control returns to the installer with the UserExit value. This argument cannot be used in a dialog box that is a child of another dialog box.
Retry | The wizard sequence is closed and the control returns to the installer with the Suspend value. This argument cannot be used in a dialog box that is a child of another dialog box.
Ignore | The wizard sequence is closed and the control returns to the installer with the Finished value. This argument cannot be used in a dialog box that is a child of another dialog box.
Return | The control returns to the parent of the present dialog box, or if there is no parent, the control returns to the installer with the Success value.

Published By

This ControlEvent is published by the installer.

Argument

On regular dialog boxes the Argument column of the ControlEvent table can be "Return", "Exit", "Retry", or "Ignore".

On error dialog boxes the Argument column of the ControlEvent table can be "ErrorOk", "ErrorCancel", "ErrorAbort", "ErrorRetry", "ErrorIgnore", "ErrorYes", or "ErrorNo".

Action on Subscribers

None.

Typical Use

A PushButton control on a modal dialog is tied to this event in the ControlEvent table to close a dialog box.


NewDialog ControlEvent

This event notifies the installer to transition a modal dialog box to another dialog box. The installer removes the present dialog and creates the new one with the name indicated in the argument.

Published By

This ControlEvent is published by the installer.

Argument

A string that is the name of the new dialog.

Action on Subscribers

None.

Typical Use

A PushButton control on a modal dialog is tied to this event in the ControlEvent table to signal a transition to the next or previous dialog of the same wizard sequence.


Reinstall ControlEvent

This ControlEvent allows the author to initiate a reinstall of some or all features, while keeping the present dialog running.

Published By

This ControlEvent is published by the installer.

Argument

A string that is either the name of the feature or "ALL".

Action on Subscribers

None.

Typical Use

A PushButton control on a modal dialog box is tied to this event and also tied to a ReinstallMode control event immediately before it.


ReinstallMode ControlEvent

This ControlEvent allows the author to specify the validation mode or modes during a reinstall while keeping the present dialog box running.

Published By

This ControlEvent is published by the installer.

Argument

A string. See the REINSTALLMODE property for a list of possible values.

Action on Subscribers

None.

Typical Use

A PushButton control on a modal dialog box is tied to this event and the same button is also tied to a Reinstall control event immediately before it.


Remove ControlEvent

The installer is notified through this event when a feature or all features are selected for removal while keeping the present dialog running.

Published By

This ControlEvent is published by the installer.

Argument

A string that is either the name of the feature or "ALL".

Action on Subscribers

None.

Action by Publisher When Subscriber Activated

The installer keeps the present dialog running and notifies the installer.

Typical Use

A PushButton control on a modal dialog tied to this event.


Reset ControlEvent

The dialog is reset. In other words, all the controls on the dialog are called to undo the property changes they have performed. This event resets all the property values to what they were when the dialog was created.

There is a case, which should occur rarely in practice, that is not handled properly by this ControlEvent. If there are two or more controls on the same dialog linked indirectly to the same property and at least one of them started having some other property, then this property value will sometimes be reset to its second value.

Published By

This ControlEvent is published by the installer.

Argument

None.

Action on Subscribers

None.

Typical Use

A PushButton control on a modal dialog is used to reset all the values on the dialog box and to cancel all the changes on the page.


ScriptInProgress ControlEvent

The installer uses this event to display an informational string while the installation's execution script is being compiled.

Published By

This ControlEvent is published by the installer.

Argument

None.

Action on Subscribers

A Text control subscribing to ScriptInProgress will display text string specified in UIText table.

Typical Use

While the execution script is being compiled, the installer displays a progress bar indicating the time remaining before the beginning of script execution. The package author can display a preliminary message at this time explaining the progress bar. To display a preliminary message, include a Text control on the same modeless dialog box as the progress bar. Specify that this Text control subscribe to the ScriptInProgress ControlEvent in the EventMapping table. Include an entry in the UIText table with ScriptInProgress specified in the Key field. Specify the preliminary message as a text string in the Text field of the UIText table. Then during script compilation, the installer will display the this string within the text control. The displayed text disappears as soon as the script compilation is finished.

The same text control that subscribes to the ScriptInProgress ControlEvent can also subscribe to the TimeRemaining ControlEvent. In this case, as text of the preliminary ScriptInProgress string disappears, it is replaced by the "Time Remaining: xx minutes" string.


SelectionAction ControlEvent

The SelectionTree control uses this event to publish a string describing the the highlighted item. The string is one of the "Sel*" strings from the UIText Table.

Published By

SelectionTree

Argument

None.

Action on Subscribers

None.

Typical Use

A Text control in the same modal dialog box as the SelectionTree uses this event to display the explanation of the selected item.


SelectionBrowse ControlEvent

The SelectionTree control uses the SelectionBrowse event to spawn a browse dialog making it possible to modify the path of the highlighted item.

Published By

SelectionTree

Argument

The name of the dialog to be spawned.

Action on Subscribers

Controls that subscribe to this event are disabled if the path of the currently selected item cannot be modified by the user.

Typical Use

A PushButton control on the same modal dialog as the SelectionTree uses this event to trigger the browse dialog.


SelectionDescription ControlEvent

The SelectionTree control uses the SelectionDescription event to publish a string that contains the description for the highlighted item. This string is the Description field of the Feature Table.

Published By

SelectionTree

Argument

None.

Action on Subscribers

None.

Typical Use

A Text control on the same modal dialog as the SelectionTree uses this event to display the description of the highlighted item.


SelectionIcon ControlEvent

The SelectionTree control uses the SelectionIcon event to publish the handle to the icon for the highlighted item.

Published By

SelectionTree

Argument

None.

Action on Subscribers

None.

Typical Use

An Icon control on the same modal dialog as the SelectionTree subscribes to this event to display the icon corresponding to the highlighted item.


SelectionNoItems ControlEvent

The SelectionTree control uses the SelectionNoItems event to delete obsolete item description text or to disable buttons that have become useless.

Published By

SelectionTree control if the selection has no nodes.

Argument

None.

Action on Subscribers

Deletes obsolete item description text or disables obsolete button.

Typical Use

May be used to disable the Next, Reset and DiskCost buttons on the SelectionDialog dialog when a selection has no nodes and these buttons become useless.


SelectionPath ControlEvent

The SelectionTree control uses the SelectionPath event to publish the path for the highlighted item. If the item is selected to run from source, then this is the path of the source. If the item is selected to be absent, then the string is the AbsentPath string from the UIText Table.

Published By

SelectionTree

Argument

None.

Action on Subscribers

None.

Typical Use

A Text control on the same modal dialog as the SelectionTree uses this event to display the path of the highlighted item.


SelectionPathOn ControlEvent

The SelectionTree control uses the SelectionPathOn event to publish a Boolean value indicating whether there is a selection path associated with the currently selected feature.

Published By

SelectionTree

Argument

None.

Action on Subscribers

None.

Typical Use

A Text control on the same modal dialog as the SelectionTree uses this event for the caption of the selection path. This text control is visible or hidden depending on the event.


SelectionSize ControlEvent

The SelectionTree control uses the SelectionSize event to publish the size of the highlighted item. If it is a parent item, then the number of children selected is also published. The string is one of the SelChildCostPos, SelChildCostNeg, SelParentCostPosPos, SelParentCostPosNeg, SelParentCostNegPos or SelParentCostNegNeg strings from the UIText Table.

Published By

SelectionTree

Argument

None.

Action on Subscribers

None.

Typical Use

A Text control on the same modal dialog as the SelectionTree uses this event to display the size of the highlighted item.


SetInstallLevel ControlEvent

The SetInstallLevel event changes the installation level to the value specified by the argument.

Published By

This ControlEvent is published by the installer.

Argument

An integer that is the new value of the installation level.

Action on Subscribers

None.

Typical Use

A PushButton control on a modal dialog is tied to this event in the ControlEvent table to change the installation level.


SetProgress ControlEvent

The installer uses the SetProgress event to publish install progress. A control has to subscribe to the event by naming the Action whose progress is being indicated.

Published By

This ControlEvent is published by the installer.

Argument

None.

Action on Subscribers

The subscribers are hidden when a new action starts and they become visible when new progress data arrives from the installer.

Typical Use

A ProgressBar control on a modeless dialog subscribes to this event using the Progress attribute to receive the progress information.


SetProperty ControlEvent

The syntax for the SetProperty event is different than for other ControlEvents In place of the name of the event one puts the property in square brackets: [property_name]. The argument is the new value of the property. To unset the property, the argument must be {}. This is necessary, because the argument is a primary key in the table and so cannot be null. The argument will be formatted using the FormatText method, therefore it can contain any expression that that method can handle. The property values are evaluated at the moment of the control event.

Published By

This ControlEvent is published by the installer.

Argument

The new value of the property. {} for null.

Action on Subscribers

None.

Typical Use

A PushButton control on a dialog linked to this event so it changes a property when the button is pushed.


SetTargetPath ControlEvent

The SetTargetPath event notifies the installer to check and set the selected path. If the path is not valid to be written to, then the installers blocks further control events associated with the control.

Published By

This ControlEvent is published by the installer.

Argument

The name of the property containing the path. If the property is indirected, then the property name is enclosed in square brackets.

Action on Subscribers

None.

Typical Use

A PushButton control on a browse dialog is tied to this event in the ControlEvent table to check the selected path before returning to the selection dialog.

Remarks

Do not attempt to configure the target path if the components using those paths are already installed for the current user or for a different user. Check the ProductState property before publishing the SetTargetPath ControlEvent to determine if the product containing the component is installed.


SpawnDialog ControlEvent

The SpawnDialog event notifies the installer to create a child of a modal dialog box while keeping the present dialog running.

Published By

This ControlEvent is published by the installer.

Argument

A string that is the name of the new dialog.

Action on Subscribers

None.

Typical Use

A PushButton control on a modal dialog is tied to this event in the ControlEvent table to create a child dialog, such as a "Are you sure you want to cancel" dialog.


SpawnWaitDialog ControlEvent

The SpawnWaitDialog event triggers the dialog specified by the Argument column of the ControlEvent table, if the expression in the Condition column evaluates as FALSE. The dialog remains up for as long as the conditional expression remains FALSE and is removed as soon as the condition evaluates TRUE.

Published By

This ControlEvent is published by the installer.

Argument

A dialog in the Dialog table.

Action on Subscribers

None.

Typical Use

The SpawnWaitDialog ControlEvent can be used to wait for any background task the completion of which can tested using a conditional expression such as the state of a property. For an example of using the SpawnWaitDialog ControlEvent, see the section Authoring a Conditional "Please wait . . ." Message Box.


TimeRemaining ControlEvent

The installer uses the TimeRemaining event to publish the approximate time remaining, in seconds, for the current progress sequence.

Published By

This ControlEvent is published by the installer.

Argument

None.

Action on Subscribers

None.

Typical Use

A text control on a modeless dialog subscribes to this event via the EventMapping table and uses the TimeRemaining attribute to display the time remaining.

The same text control that subscribes to the TimeRemaining ControlEvent can also subscribe to the ScriptInProgress ControlEvent. In this case, as the preliminary ScriptInProgress message string, it is replaced by the "Time Remaining: xx minutes" string.


ValidateProductID ControlEvent

The ValidateProductID event sets the ProductID property to the full Product ID. If the validation is unsuccessful, then this event puts up an error message and modal dialog for a user entry of the Product ID.

Published By

This ControlEvent is published by the installer.

Argument

None.

Action on Subscribers

None.

Typical Use

A PushButton control on a modal dialog is tied to this event and is used to check the user's entry of the Product ID. If the user's entry is valid, then the next dialog will open.


Standard Actions

An action encapsulates a typical function performed during the installation or maintenance of an application. The Microsoft® Windows® Installer has many built-in standard actions. Developers of installation packages can also author their own custom actions.

Examples of installer standard actions include:

  • CreateShortcuts action: Manages the creation of shortcuts to files installed with the current application. This action uses the Shortcut table for its data.
  • InstallFiles action: Copies selected files from the source directory to the destination directory. This action uses the File table for its data.
  • WriteRegistryValues action: Sets up registry information the application requires in the registry. This action uses the Registry table for its data.

The following sections discuss standard actions.

  • About Standard Actions
  • Using Standard Actions
  • Standard Actions Reference


About Standard Actions

The Microsoft® Windows® Installer has many built-in standard actions that are used in the sequence tables. The topics in this section cover information about standard actions.

  • Action Execution Order
  • Actions with Sequencing Restrictions
  • Actions without Sequencing Restrictions

See also Using Standard Actions or Standard Actions Reference.


Action Execution Order

The order of action execution is determined by the sequence of actions that have been authored into the sequence tables and by the order in which the installer runs the sequence tables. For details, see the suggested action sequences in Using a Sequence Table.

The installer runs sequence tables in response to a request for an installation, advertisement, or an administrative installation. For example, in response to using the /I, /J, or /A command line options, the INSTALL, ADVERTISE, and ADMIN actions are not called from within the action sequence. These high-level actions are instead passed to the installer when the installer is initialized.

If the installer is passed the INSTALL action and the installation package has been authored with a user interface, the installer first runs the actions in InstallUISequence table and then executes the actions in the InstallExecuteSequence table in order. If the package has no user interface, the installer executes the actions in the InstallExecuteSequence table in order.

If the installer is passed the ADVERTISE action, and the installation package has been authored with a user interface, the installer runs the AdvtExecute table. If the package has no user interface, the installer runs the AdvtExecute table.

If the installer is passed the ADMIN action, and the installation package has been authored with a user interface, the installer first runs the AdminUISequence table and then runs the AdminExecuteSequence table. If the package has no user interface, the installer runs the AdminExecute table.

When the installer runs a sequence table, it executes actions in the order of the sequence numbers listed in the Sequence column. The action order is always linear with no branching or looping. Package developers can conditionally prevent a particular action from being executed by authoring a logical expression into the Condition column. The installer skips the action whenever the condition evaluates to False. See Using a Sequence Table and Conditional Statement Syntax.

All sequence tables have the following columns.

Column | Description
Action | The primary key for the table; the action name must be unique.
Condition | A Boolean expression used to determine whether to perform the action. The action is executed if this field is either blank or contains an expression that evaluates to True. The action is not executed if the expression evaluates to False.
Sequence | A relative sequence number used to determine the order in which actions are executed.


Actions with Sequencing Restrictions

The sequencing of many actions in the actions tables is restricted. See Standard Actions Reference for a complete list of actions with links to detailed sequencing information.

The sequencing of the following actions is restricted.

AllocateRegistrySpace

BindImage

CCPSearch

CostFinalize

CostInitialize

CreateFolders

CreateShortcuts

DeleteServices

DuplicateFiles

ExecuteAction

FileCost

ForceReboot

InstallExecute

InstallFiles

InstallFinalize

InstallInitialize

InstallValidate

LaunchConditions

MoveFiles

InstallODBC

InstallServices

PatchFiles

PublishFeatures

PublishProduct

RegisterClassInfo

RegisterExtensionInfo

RegisterFonts

RegisterMIMEInfo

RegisterProgIdInfo

RegisterTypeLibraries

RemoveEnvironmentStrings action

RemoveFiles

RemoveDuplicateFiles

RemoveFolders

RemoveIniValues

RemoveRegistryValues

RemoveShortcuts

ResolveSource

SelfRegModules

SelfUnregModules

SetODBCFolders

StartServices

StopServices

UnregisterClassInfo

UnregisterExtensionInfo

UnregisterFonts

UnregisterMIMEInfo

UnregisterProgIdInfo

UnregisterTypeLibraries

WriteEnvironmentStrings

WriteIniValues

WriteRegistryValues

RegisterComPlus

UnregisterComPlus


Actions without Sequencing Restrictions

The sequencing of the following actions is unrestricted. These actions can be placed anywhere in the action sequence.

AppSearch

DisableRollback

InstallAdminPackage

RemoveODBC

ProcessComponents

PublishComponents

RegisterProduct

RegisterUser

RMCCPSearch

ScheduleReboot

UnpublishComponents

UnpublishFeatures


Using Standard Actions

An action is executed in the Microsoft® Windows® Installer either by calling the MsiDoAction function or including the action in a sequence table. Because most actions encapsulate a single purpose, the most common way to use actions is to order a series of actions into a sequence to accomplish a larger task. The installer has three standard top-level actions that call an associated set of sequence tables. These associated sequence tables may contain standard actions, custom actions, and user-interface elements. Each action in a sequence table has an associated sequence number and may also have an associated conditional expression. All actions in a sequence table are visited in order and are only executed if the conditional expression evaluates to True.

While a standard action can have any sequence number associated with it, many have sequence restrictions which must be followed for the action to function properly. For example the FileCost action, must be called after the CostInitialize action. For more information on standard action sequencing restrictions, see Actions with Sequencing Restrictions, Actions without Sequencing Restrictions, or Standard Actions Reference.

The following topics provide more information about using standard actions.

  • Publishing Products, Features, and Components
  • File Searching
  • File Costing
  • File Installation
  • Modifying the Registry
  • Running Actions

See also About Standard Actions or Standard Actions Reference.


Publishing Products, Features, and Components

To publish a product, component, or feature, use one of the publishing actions. The PublishProduct action registers the product information with the system. After executing the PublishProduct action, publish the components with the PublishComponents action, which in turn uses the PublishComponent table to determine the components that are set as advertised. To publish on a per-feature basis, invoke the PublishFeatures action. This action uses the FeatureComponents table as data to resolve which features are advertised.

There are also two corresponding actions that unpublish a feature or a component: the UnpublishComponents action and the UnpublishFeatures action.


File Searching

During installation, there is often the need to search for a specific file. The installer has four standard search actions to serve this purpose. The AppSearch action uses the AppSearch table to determine if a file exists on a user's system. During an upgrade installation, the CCPSearch action and the RMCCPSearch action can use their corresponding tables to check the user's system for a previous version of a product.


File Costing

Costing is the process of determining the total disk space requirements for an installation. The elements calculated in the file costing process include the amount of disk space in which files are installed or removed, and the amount of disk space taken up by registry entries, shortcuts, and other miscellaneous files. Existing files scheduled to be overwritten are also calculated in the disk cost totals.

Total costs are accumulated on a per-component basis and consist of three separate parts: local costs, source costs, and removal costs. These parts correspond to the disk cost that is incurred if the component is installed locally, installed to run from the source media, or removed.

All calculations involving the cost of installing files depend upon the disk volume to which the file is to be installed or removed. Each time the directory associated with a component changes, the costs of the installation files controlled by that component must be recalculated. For example, because a directory change might also imply a volume change, the clustered file sizes must be recalculated. In addition, the new directory must be checked to determine whether any existing files that may be overwritten must be taken into account.

After the CostInitialize action is called, the FileCost action must be called. The CostInitialize action initializes the installer's internal routines that dynamically calculate the disk costs involved with the standard installation actions. No other dynamic cost calculations are done at this point.

Next, the CostFinalize action must be called. This action finalizes all cost calculations and makes the costing data available through the Component table.

After the CostFinalize action completes execution, the Component table is fully initialized and a user interface dialog box sequence containing a SelectionTree control can be initiated if needed. The user interface dialog boxes may offer the option to change the selection state or destination directory of any feature in the Feature table to the user. The process is similar when the selection state of a component changes; however, in this case, the dynamic cost of the changed component only is recalculated.

Once the user has completed selecting features in the user interface, the InstallValidate action should be called. This action verifies that all volumes to which cost has been attributed have sufficient space for the installation.


File Installation

Once file costing, the installer has all the information needed to process the two file manipulation actions: DuplicateFiles and MoveFiles.

Use the DuplicateFiles action. Specify the files the installer is to duplicate in the DuplicateFile table.

Use the MoveFiles action. The MoveFiles action determines which files to move by querying the MoveFile table.

Note that the Options field of the MoveFile table specifies whether or not the original file is to be deleted from its current location. Files that are moved or copied by the MoveFiles action are not deleted when the product is uninstalled.

The InstallFiles action is called once all other file manipulation operations have completed. The InstallFiles action processes the Media table, the File table, and the Component table to determine which files will be copied from the source to the destination.

The InstallFiles action will create the directory structure necessary to install all files. If an explicitly empty folder is required to be installed, the CreateFolders action may be called to create it.


Modifying the Registry

Registry keys can be written to the system registry once all selected components and their related files have been installed. The standard actions related to modifying the registry must be sequenced after the file installation standard actions because registry keys cannot be written unless the corresponding component and file have been successfully installed.

The RegisterClassInfo action accesses the Class table to register the COM class information of the installed components.

The RegisterExtensionInfo action queries the Extension table and Verb table and registers the corresponding extensions and command-verb information with the operating system.

The RegisterProgIdInfo action manages the registration of OLE ProgId information with the operating system.

The RegisterMIMEInfo action processes the MIME table to register the association between a MIME context type, the file extension, and the CLSID.

The WriteRegistryValues action processes the Registry table and writes the keys for all components that have been either installed locally or to run from source. The Registry table allows keys to be written to the HKEY_CLASSES_ROOT, HKEY_CURRENT_USER, HKEY_LOCAL_MACHINE, and HKEY_USERS registry hives.

The RemoveRegistryValues action removes the keys that have been marked to be deleted in the Name column of the Registry table or the RemoveRegistry Table.

The RegisterTypeLibraries action processes the TypeLib table and registers the installed type libraries with the system.


Running Actions

The installer functions can be used to run specific actions or action sequences. These actions can either be standard or custom actions. The following procedure describes how to run actions:

To run an action sequence

  1. Run a sequence of actions defined in a table by calling the MsiSequence function.

    The installer queries the indicated table and runs each action if its conditional expression evaluates to TRUE.

  2. Check conditional expressions by calling the MsiEvaluateCondition function.
  3. Run the action by calling the MsiDoAction function. The action can be a standard action, a custom action, or a user interface dialog box.
  4. If an error occurred during the execution of this action, call the MsiProcessMessage function. The installer will processes the error.


Standard Actions Reference

The Microsoft® Windows® Installer has the following standard actions.

Action name | Brief description of action
ADMIN | A top-level action used for an administrative installation.
ADVERTISE | A top-level action called to install or remove advertised components.
AllocateRegistrySpace | Validates that the free space specified by AVAILABLEFREEREG exists in the registry.
AppSearch | Searches for previous versions of products and determines upgrades are installed.
BindImage | Binds executables to imported DLLs.
CCPSearch | Uses file signatures to validate that qualifying products are installed on a system before an upgrade installation is performed.
CostFinalize | Ends the internal installation costing process begun by the CostInitialize action.
CostInitialize | Starts the installation costing process.
CreateFolders | Creates empty folders for components.
CreateShortcuts | Creates shortcuts.
DeleteServices | Removes system services.
DisableRollback | Disables rollback for the remainder of the installation.
DuplicateFiles | Duplicates files installed by the InstallFiles action.
ExecuteAction | Checks the EXECUTEACTION property to determine which top-level action begins the execution sequence, then runs that action.
FileCost | Initializes disk cost calculation with the Installer. Disk costing is not finalized until the CostFinalize action is executed.
FindRelatedProducts | Detects correspondence between the Upgrade table and installed products.
ForceReboot | Used in the action sequence to prompt the user for a reboot of the system during the installation.
INSTALL | A top-level action called to install or remove components.
InstallAdminPackage | Copies the installer database to the administrative installation point.
InstallExecute | Runs a script containing all operations spooled since either the start of the installation or the last InstallFinalize action. Does not end the transaction.
InstallFiles | Copies files from the source to the destination directory.
InstallFinalize | Runs a script containing all operations spooled since either the start of the installation or the last InstallFinalize action. Marks the end of a transaction.
InstallInitialize | Marks the beginning of a transaction.
InstallSFPCatalogFile | The InstallSFPCatalogFile action installs the catalogs used by Microsoft® Windows® Millennium Edition for Windows File Protection.
InstallValidate | Verifies all volumes with attributed costs have sufficient space for the installation.
IsolateComponents | Processes the IsolatedComponent table
LaunchConditions | Evaluates a set of conditional statements contained in the LaunchCondition table that must all evaluate to True before the installation will proceed.
MigrateFeatureStates | Migrates current feature states to the pending installation.
MoveFiles | Locates existing files and moves or copies those files to a new location.
MsiPublishAssemblies action | Manages the advertisement of common language runtime assemblies and Win32 assemblies that are being installed. This action requires Windows Installer Version 1.5 or later versions.
MsiUnpublishAssemblies action | Manages the advertisement of common language runtime assemblies and Win32 assemblies that are being removed. This action requires Windows Installer Version 1.5 or later versions.
InstallODBC | Installs the ODBC drivers, translators, and data sources.
InstallServices | Registers a service with the system.
PatchFiles | Queries the Patch table to determine which patches are applied to specific files and then performs the byte-wise patching of the files.
PreventInstall | Blocks the pending installation.
ProcessComponents | Registers components, their key paths, and component clients.
PublishComponents | Advertises the components specified in the PublishComponent table.
PublishFeatures | Writes the feature state of each feature into the system registry
PublishProduct | Publishes product information with the system.
RegisterClassInfo | Manages the registration of COM class information with the system.
RegisterComPlus | The RegisterComPlus action registers COM+ applications.
RegisterExtensionInfo | Registers extension related information with the system.
RegisterFonts | Registers installed fonts with the system.
RegisterMIMEInfo | Registers MIME information with the system.
RegisterProduct | Registers product information with the installer and stores the installer database on the local computer.
RegisterProgIdInfo | Registers OLE ProgId information with the system.
RegisterTypeLibraries | Registers type libraries with the system.
RegisterUser | Registers user information to identify the user of a product.
RemoveDuplicateFiles | Deletes files installed by the DuplicateFiles action.
RemoveEnvironmentStrings | Modifies the values of environment variables.
RemoveExistingProducts | Removes installed versions of a product.
RemoveFiles | Removes files previously installed by the InstallFiles action.
RemoveFolders | Removes empty folders linked to components set to be removed.
RemoveIniValues | Deletes .ini file information associated with a component specified in the IniFile table.
RemoveODBC | Removes ODBC data sources, translators, and drivers.
RemoveRegistryValues | Removes an application's registry keys that were created from the Registry table..
RemoveShortcuts | Manages the removal of an advertised shortcut whose feature is selected for uninstall.
ResolveSource | Determines the source location and sets the SourceDir property.
RMCCPSearch | Uses file signatures to validate that qualifying products are installed on a system before an upgrade installation is performed.
ScheduleReboot | Prompts the user for a system reboot at the end of the installation.
SelfRegModules | Processes modules in the SelfReg table and registers them if they are installed.
SelfUnregModules | Unregisters the modules in the SelfReg table that are set to be uninstalled.
SEQUENCE | Runs the actions in a table specified by the SEQUENCE property.
SetODBCFolders Action | Checks the system for existing ODBC drivers and sets target directory for new ODBC drivers.
StartServices | Starts system services.
StopServices | Stops system services.
UnpublishComponents | Manages the unadvertisement of components from the PublishComponent table and removes information about published components.
UnpublishFeatures | Removes the selection-state and feature-component mapping information from the system registry.
UnregisterClassInfo | Manages the removal of COM classes from the system registry.
UnregisterComPlus | The UnregisterComPlus action removes COM+ applications from the registry.
UnregisterExtensionInfo | Manages the removal of extension-related information from the system.
UnregisterFonts | Removes registration information about installed fonts from the system.
UnregisterMIMEInfo | Unregisters MIME-related information from the system registry.
UnregisterProgIdInfo | Manages the unregistration of OLE ProgId information with the system.
UnregisterTypeLibraries | Unregisters type libraries with the system.
ValidateProductID | Sets ProductID property to the full product identifier.
WriteEnvironmentStrings | Modifies the values of environment variables.
WriteIniValues | Writes .ini file information.
WriteRegistryValues | Sets up registry information.


ADMIN Action

The ADMIN action is a top-level action used to perform administrative installations.

Sequence Restrictions

None.

ActionData Messages

None.

Remarks

The ADMIN action is not called from within the action table sequence, Windows Installer executes this action when MsiInstallProduct is called with the szCommandLine parameter set to "ACTION=ADMIN" or the command line executable Msiexec.exe is called with the '/a' command line switch.

See Also

AdminUISequence Table, AdminExecuteSequence Table


ADVERTISE Action

The ADVERTISE action is a top-level action called to install or remove advertised components.

Sequence Restrictions

None.

ActionData Messages

None.

Remarks

Advertising refers to the installer's ability to provide the loading and launching interfaces of an application without physically installing the application. The installer does not install the necessary components until a user or application activates an advertised interface. This concept is called install-on-demand.

The ADVERTISE action is not called from within the action table sequence, Windows Installer executes this action when the command line executable Msiexec.exe is called with the '/j' command line switch or when MsiInstallProduct is called with the szCommandLine parameter set to ACTION=ADVERTISE.

See Also

AdvtExecuteSequence Table


AllocateRegistrySpace Action

The AllocateRegistrySpace action ensures that the amount of free registry space specified by the AVAILABLEFREEREG property exists in the registry.

Sequence Restrictions

The AllocateRegistrySpace action must be called after InstallInitialize. It is advisable to schedule the AllocateRegistrySpace before all other actions to ensure there is enough registry space available to continue.

ActionData Messages

Field | Description of action data
[1] | Registry space required in KB

Remarks

This action is not enabled on Windows 95 or Windows 98.


AppSearch Action

The AppSearch action uses file signatures to search for existing versions of products. The AppSearch action may use this information to determine where upgrades are to be installed. The AppSearch action can also be used to set a property to the existing value of an registry or .ini file entry.

Sequence Restrictions

None.

ActionData Messages

Field | Description of action data
[1] | Property holding file location
[2] | File signature

Remarks

The AppSearch action searches for file signatures using the CompLocator table first, the RegLocator table next, then the IniLocator table, and finally the DrLocator table.

File signatures are listed in the Signature table. A signature that is not in the Signature table denotes a directory and the action sets the property to the directory path for that signature.

See Also

AppSearch, CompLocator, IniLocator, RegLocator, DrLocator tables


BindImage Action

The BindImage action binds each executable or DLL that must be bound to the DLLs imported by it. The BindImage action acts on each file in the BindImage table, but only those that are to be installed locally. The installer computes the virtual address of each function imported from all DLLs, then saves the computed virtual address in the importing image's import address table (IAT).

The BindImage Action internally calls the BindImageEx Windows API.

Sequence Restrictions

The BindImage action must come after the InstallFiles action.

ActionData Messages

Field | Description of action data
[1] | File identifier of executable


CCPSearch Action

The CCPSearch action uses file signatures to validate that qualifying products are installed on a system before an upgrade installation is performed.

Sequence Restrictions

The CCPSearch action must come before the RMCCPSearch action.

ActionData Messages

None.

Remarks

The CCPSearch action searches for file signatures listed in the CCPSearch table on the system using the following tables in order: Signature, CompLocator, RegLocator, IniLocator, and DrLocator.

If any signature is determined to exist, the CCP_Success property is set to 1 and the CCPSearch action terminates.

The absence of the signature from the Signature table denotes a directory.

See Also

CCPSearch, Signature, CompLocator, RegLocator, IniLocator, DrLocator tables


CostFinalize Action

The CostFinalize action ends the internal installation costing process begun by the CostInitialize action.

Sequence Restrictions

The CostInitialize action and any cost-calculation actions, such as the FileCost action, must be executed prior to the CostFinalize action.

The CostFinalize action must be executed before starting any user interface sequence which allows the user to view or modify Feature table selections or directories.

ActionData Messages

None.

Remarks

The CostFinalize action queries the Condition table to determine which features are scheduled to be installed. Costing is done for each component in the Component table.

The CostFinalize action also verifies that all the target directories are writable before allowing the installation to continue.


CostInitialize Action

The CostInitialize action initiates the installation costing process.

Sequence Restrictions

The FileCost action is called immediately following the CostInitialize action. The CostFinalize action is then called, which finalizes all cost calculations and makes them available to the installer through the Component table.

ActionData Messages

None.

Remarks

The CostInitialize action loads the Component table and Feature table into memory.

For more information on the costing process in the installer, see File Costing.


CreateFolders Action

The CreateFolders action creates empty folders for components that are set to be installed. The installer creates folder both for components run locally and run from source. Newly created folders are registered with the appropriate component identifier.

The CreateFolders action queries the CreateFolder table. and the Component table.

Sequence Restrictions

The CreateFolders action must be executed either before the InstallFiles action or before any action that adds files to folders.

ActionData Messages

Field | Description of action data description
[1] | Directory identifier of folder

Remarks

The installer does not automatically remove folders created by the CreateFolders action during an uninstall of the application. The installer only removes folders if the RemoveFolders action is included in the action sequence.


CreateShortcuts Action

The CreateShortcuts action manages the creation of shortcuts.

Sequence Restrictions

The CreateShortcuts action must come after the InstallFiles action and the RemoveShortcuts action.

ActionData Messages

Field | Description of action data
[1] | Identifier of created shortcut

Remarks

The CreateShortcuts action creates shortcuts to the key files of components of features that are selected for installation or advertisement.

See Also

Shortcut Table


DeleteServices Action

The DeleteServices action stops a service and removes its registration from the system. This action queries the ServiceControl table.

Sequence Restrictions

The services actions must be used in the following sequence:

  1. StopServices
  2. DeleteServices
  3. Any of the following actions: InstallFiles, RemoveFiles, DuplicateFiles, MoveFiles, PatchFiles, and RemoveDuplicateFiles actions.
  4. InstallServices action
  5. StartServices

ActionData Messages

Field | Description of action data
[1] | Service display name.
[2] | Service name

Remarks

This action requires the user be an administrator or have elevated privileges with permission to delete services or that the application be part of a managed installation.


DisableRollback Action

The DisableRollback Action disables rollback for the remainder of the installation. Rollback is disabled only for the actions that are sequenced after the DisableRollback action in the sequence tables. Rollback is disabled for the entire installation if the DisableRollback action is sequenced before the InstallInitialize action.

Sequence Restrictions

None.

ActionData Message

None.


DuplicateFiles Action

The DuplicateFiles action duplicates files installed by the InstallFiles action. The duplicate files can be copied to the same directory with a different name or to a different directory with the original name.

Sequence Restrictions

The DuplicateFiles action must come after the InstallFiles action. The DuplicateFiles Action must also come after the PatchFiles action to prevent duplicating the unpatched version of the file.

ActionData Messages

Field | Description of action data
[1] | Identifier of duplicated file
[6] | Size of duplicated file
[9] | Identifier of directory holding duplicated file

Remarks

The DuplicateFiles action processes a DuplicateFile table entry only if the component linked to that entry is being installed locally. For more information, see Component table.

The string in the DestFolder field is a property name whose value is expected to resolve to a fully qualified path. This property can either be any of the directory entries in the Directory table, any pre-defined folder property (CommonFilesFolder, for example), or a property set by any entry in the AppSearch table. If the DestFolder property does not evaluate to a valid path the DuplicateFiles action does nothing for that entry.

If the name of the destination file in the DestName column of the DuplicateFile table is left blank, the destination file name will be the same as the original file name.

Files installed by the DuplicateFiles action are removed by the RemoveDuplicateFiles action when appropriate.


ExecuteAction Action

The ExecuteAction action initiates the execution sequence using the EXECUTEACTION property to determine which type of installation to perform.

Sequence Restrictions

This action should be sequenced after all information collection necessary to begin the installation is complete. Additional actions may be sequenced after ExecuteAction action in the InstallUISequence table, and AdminUISequence table. A sequence will typically begin with costing actions, such as the CostInitialize action, followed by the user interface actions, and then the ExecuteAction action.

ActionData Messages

None.

Remarks

The ExecuteAction action is run with system privileges if the installer service is enabled. The top-level actions, such as the INSTALL action, ADVERTISE action, and ADMIN action include internal logic that determines whether calling the ExecuteAction action requires either the execution sequence or the user interface sequence to run.

See Also

InstallUISequence table, AdminUISequence table, CostInitialize action


FileCost Action

The FileCost action initiates dynamic costing of standard installation actions.

ActionData Messages

None.

Sequence Restrictions

The CostInitialize action must be executed before the FileCost action. The installer then determines the disk-space cost of every file in the File table, on a per-component basis (See Component Table), taking both volume clustering and the presence of existing files that may need to be overwritten into account. All actions that consume or release disk space are also considered. If an existing file is found, a file version check is performed to determine whether the new file actually needs to be installed or not. If the existing file is of an equal or greater version number, the existing file is not overwritten and no disk-space cost is incurred. In all cases, the installer uses the results of version number checking to set the installation state of each file.

The FileCost action initializes cost calculation with the installer. Actual dynamic costing does not occur until the CostFinalize action is executed.


FindRelatedProducts Action

The FindRelatedProducts action runs through each record of the Upgrade table in sequence and compares the upgrade code, product version, and language in each row to products installed on the system. When FindRelatedProducts detects a correspondence between the upgrade information and an installed product, it appends the product code to the property specified in the ActionProperty column of the UpgradeTable.

Database Tables Queried

This action queries the following table:

Upgrade Table

Properties Used

The FindRelatedProducts action uses the UpgradeCode property and the version and language information authored into the Upgrade table to detect installed products affected by the pending upgrade. It appends the product code of detected products to the property in the ActionProperty column of the UpgradeTable.

FindRelatedProducts only recognizes existing products that have been installed using the Windows Installer with an .msi that defines an UpgradeCode property, a ProductVersion property, and a value for the ProductLanguage property that is one of the languages listed in the Template Summary Property.

Note that FindRelatedProducts uses the language returned by MsiGetProductInfo. For FindRelatedProducts to work correctly, the package author must be sure that the ProductLanguage property in the Property table is set to a language that is also listed in the Template Summary Property. See Preparing an Application for Future Major Upgrades.

Sequence Restrictions

FindRelatedProducts should be authored into the InstallUISequence table and InstallExecuteSequence tables. The installer prevents FindRelated Products from running in InstallExecuteSequence if the action has already run in InstallUISequence. The FindRelatedProducts action must come before the MigrateFeatureStates action and the RemoveExistingProducts action.

ActionData Messages

FindRelatedProducts sends an action data message for each related product it detects installed on the system.


ForceReboot Action

The ForceReboot action prompts the user for a reboot of the system during the installation. The ForceReboot action is different from the ScheduleReboot action in that the ScheduleReboot action is used to schedule a prompt to reboot at the end of the installation.

If the installation has a user interface, the installer displays a dialog box at each ForceReboot action which prompts the user to reboot the system. The user must respond to this prompt before continuing with the installation. If the installation has no user interface, the system automatically reboots at the ForceReboot action.

If the installer determines that a reboot is necessary, it automatically prompts the user to reboot at the end of the installation, whether or not there are any ForceReboot or ScheduleReboot actions in the sequence. For example, the installer automatically prompts for a reboot if it needs to replace any files that are in use during the installation.

Suppress certain reboot prompts by setting the REBOOT property.

Sequence Restrictions

The following actions commonly occur together as a group in the action sequence. It is recommended that the ForceReboot action be scheduled to come after this group. If the ForceReboot action is scheduled before the RegisterProduct action, the installer again requires the source of the installation package after the reboot. Therefore, the preferred sequence for ForceReboot is immediately following this action sequence.

RegisterProduct

RegisterUser

PublishProduct

PublishFeatures

CreateShortcuts

RegisterMIMEInfo

RegisterExtensionInfo

RegisterClassInfo

RegisterProgIdInfo

The ForceReboot action must come between InstallInitialize and InstallFinalize in the action sequence of the InstallExecuteSequence table.

ActionData Messages

None.

Remarks

The ForceReboot action must always be used with a conditional statement such that the installer triggers a reboot only when necessary. For example, a reboot may only be required if a particular file is replaced or a particular component is installed. Each product installation is unique and a custom action may be required to determine whether a reboot is needed. The condition on the ForceReboot action commonly makes use of the AFTERREBOOT property.

ForceReboot runs system operations generated by any previous actions before prompting for a reboot or rebooting. For example, the system operations generated by InstallFiles and WriteRegistryValues are run before a reboot.

The ForceReboot action writes a registry key that causes the installer to start after rebooting. The location of this key is
HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\RunOnce.

See Also

System Reboots


INSTALL Action

The INSTALL action is a top-level action called to install or remove components. This action queries the InstallUISequence Table and InstallExecuteSequence Table for the action to execute, the condition for action execution, and the place of the action in the sequence:

Sequence Restrictions

None.

ActionData Messages

None.

Remarks

The INSTALL action is not called from within the action table sequence, it is passed to Windows Installer when MsiInstallProduct is called, or the command line executable Msiexec.exe is called with the '/i' command line switch, or when any Windows Installer function is called that may perform an installation task, such as MsiConfigureFeature, MsiProvideComponent, or MsiInstallMissingFile.


InstallAdminPackage Action

The InstallAdminPackage action copies the product database to the administrative installation point, which is defined by the TARGETDIR property.

Sequence Restrictions

None.

ActionData Messages

Field | Description of action data
[1] | Name of install files
[6] | Size of database
[9] | Identifier of administrative installation point directory

Remarks

The InstallAdminPackage action also updates the summary information of the database and removes any cabinet files located in streams after the database is copied.


InstallExecute Action

The InstallExecute action runs a script containing all operations spooled since either the start of the installation or the last InstallExecute action or InstallExecuteAgain action. The InstallExecute action updates the system without ending the transaction.

Sequence Restrictions

The InstallExecute action comes between the InstallInitialize action and the InstallFinalize action.

ActionData Messages

None.

Remarks

The InstallExecuteAgain action does the same thing as the InstallExecute action. Because the sequence tables have only one primary key, the Action column, the same action cannot be repeated in a particular sequence table. Two actions exist that do the same thing, InstallExecute and InstallExecuteAgain, for cases where the functionality of InstallExecute is needed twice in the InstallExecuteSequence table. For more information, see Using a Sequence Table.


InstallExecuteAgain Action

The InstallExecuteAgain action runs a script containing all operations spooled since either the start of the installation or the last InstallExecuteAgain action or the last InstallExecute action. The InstallExecute action updates the system without ending the transaction. InstallExecuteAgain performs the same operation as the InstallExecute action but should only be used after InstallExecute.

Sequence Restrictions

The InstallExecute action comes between the InstallInitialize action and the InstallFinalize action.

ActionData Messages

None.

Remarks

The InstallExecuteAgain action does the same thing as the InstallExecute action. Because the sequence tables have only one primary key, the Action column, the same action cannot be repeated in a particular sequence table. Two actions exist that do the same thing, InstallExecute and InstallExecuteAgain, for cases where the functionality of InstallExecute is needed twice in the InstallExecuteSequence table. For more information, see Using a Sequence Table.


InstallFiles Action

The InstallFiles action copies files specified in the File table from the source directory to the destination directory.

Sequence Restrictions

The InstallFiles action must come after the InstallValidate action and before any file-dependent actions.

ActionData Messages

Field | Description of action data
[1] | Identifier of installed file
[6] | Size of installed file in bytes
[9] | Identifier of directory holding installed file

Remarks

The InstallFiles action operates on files specified in the File table. Each file is installed based on the installation state of the file's associated component in the Component table. Only those files whose components are resolved to the msiInstallStatelocal state are eligible for copying.

The InstallFiles action implements the following columns of the File table.

  • The FileName column specifies the target file name.
  • The Version column specifies the file version.
  • The Attributes column specifies the file and installation attribute flag bits.
  • The File column specifies the unique file token.
  • The FileSize column specifies the uncompressed file size in bytes.
  • The Language column specifies the file language identifier.
  • The Sequence column specifies the sequence number on media.

The InstallFiles action implements the following columns of the Component table.

  • The Directory_ column specifies a reference to a Directory table item.
  • The Component column specifies a unique name for the component item.

The specified file is copied only if one of the following is true:

  • The file is not currently installed on the local computer.
  • The file is on the local computer but has a lower version number than the file in the File table.
  • The file is on the local computer, but there is no associated version number.

The source directory for each file to be copied is determined by the sourceMode, which in turn depends on the value in the Cabinet column of the Media table. For a full discussion of the source mode, see the Media table.

If the source directory for a file to be copied resides on removable media such as a floppy disk or CD-ROM, the InstallFiles action verifies that the proper source media is inserted before attempting to copy the file. The InstallFiles searches for media of the same removable type with a volume label that matches the value given in the VolumeLabel column of the Media table. If a matching mounted volume is found, the file copying process proceeds. If no match is found, a dialog box requests that the user to insert the proper media. In this case, the dialog box uses the media name found in the DiskPrompt column of the Media table as part of the prompt.

Caution must be exercised because it is possible that the InstallFiles action will delete an original file and not replace it. This occurs if the InstallFiles action experiences an error while replacing an older file and the user chooses to ignore the error. This results because the default behavior of installer is to delete an old file before ensuring the new file is copied correctly.

For the file versioning rules used by the installer, see File Versioning Rules.


InstallFinalize Action

The InstallFinalize action runs a script containing all operations spooled since either the start of the installation or the last InstallFinalize action. This action marks the end of a transaction that begins with the InstallInitialize action.

Sequence Restrictions

The InstallInitialize action must come before the InstallFinalize action.

ActionData Messages

None.

Remarks

If it is detected that the product is marked for complete removal, operations are automatically added to the script to remove the Add/Remove Control Panel information for the product, to unregister and unpublish the product, and to remove the cached local database from %WINDOWS%, if it exists.

System changes made before the action may not be restored after the InstallFinalize action is executed. The InstallFinalize action updates the system with all operations determined to that point and then ends the transaction.


InstallInitialize Action

The InstallInitialize action and InstallFinalize action mark the beginning and end of a sequence of actions that change the system.

Sequence Restrictions

The InstallInitialize action must be sequenced before any actions that change the system, such as the InstallFiles action, the WriteRegistryValues action, and the ProcessComponents action. The InstallInitialize action must therefore be sequenced before the InstallFinalize action and the InstallExecute action.

ActionData Messages

None.


InstallODBC Action

The InstallODBC action installs the drivers, translators, and data sources in the ODBCDriver table, ODBCTranslator table, and ODBCDataSource table. If a driver or translator already exists, the InstallODBC action makes SQL calls necessary to carry out the installation.

Sequence Restrictions

The InstallODBC action does not copy or remove files and therefore must come after actions that copy or remove files.

ActionData Messages

For each driver installed.

Field | Description of action data
[1] | Driver description. The ODBC driver key.
[2] | ComponentId
[3] | Folder
[4, 5, …] | Attribute and Value pairs from ODBCAttribute.

For each translator installed.

Field | Description of action data
[1] | Driver description. The ODBC driver key.
[2] | ComponentId
[3] | Folder
[4, 5, …] | Attribute and Value pairs from ODBCAttribute.

For each data source installed.

Field | Description of action data
[1] | Driver description. The ODBC driver key.
[2] | ComponentId
[3] | Registration: ODBC_ADD_DSN or ODBC_ADD_SYS_DSN
[4, 5, …] | Attribute and Value pairs from ODBCAttribute.

Remarks

The ODBC Driver Manager must be authored in the installer package and a component named ODBCDriverManager must be included. The manager will be installed if necessary. To rename the component set a property named ODBCDriverManager to the new name of the component.

The InstallODBC action queries the ODBCDataSource table and the ODBCSourceAttribute table for each data source to be installed and the attributes of the data source. The InstallODBC action queries the ODBCDriver table and the ODBCTranslator table for each driver and translator selected for installation. The InstallODBC action queries the ODBCAttribute table for the attributes of the drivers and translators.


InstallServices Action

The InstallServices action registers a service for the system. This action queries the ServiceInstall table.

Sequence Restrictions

The services action must be used in the following sequence.

StopServices

DeleteServices

Any of the following actions: InstallFiles, RemoveFiles, DuplicateFiles, MoveFiles, PatchFiles, and RemoveDuplicateFiles actions.

InstallServices

StartServices

ActionData Messages

None.

Remarks

This action requires that the user be an administrator or have elevated privileges with permission to install services or that the application be part of a managed installation.


InstallSFPCatalogFile Action

The InstallSFPCatalogFile action installs the catalogs used by Microsoft® Windows® Millennium Edition for Windows File Protection. InstallSFPCatalogFile queries the Component table, File table, FileSFPCatalog table and SFPCatalog table. Catalogs are installed if they are associated with a file in a component that is set for local installation or if they are associated with a file being repaired in a locally installed component.

Sequence Restrictions

The InstallSFPCatalogFile action must be sequenced before InstallFiles and after CostFinalize.

ActionData Messages

Field | Description of action data
[1] | Name of the catalog being installed.
[2] | Name of the catalog this catalog's installation depends upon.

Remarks

A catalog the is dependent on another catalog that is installed after the parent catalog.

This feature is not available using Windows Installer versions 1.0 and 1.1.

Windows File Protection for Windows Millennium Edition is provided with Windows Installer version 1.2. For more information, see Windows File Protection on Windows Millennium Edition.


InstallValidate Action

The InstallValidate action verifies that all volumes to which cost has been attributed have sufficient space for the installation. The InstallValidate action ends the installation with a fatal error if any volume is short of disk space.

The InstallValidate action also notifies the user if one or more files to be overwritten or removed are currently in use by an active process. For more information, see System Reboots.

Sequence Restrictions

The CostFinalize action and any user-interface dialog box sequences that allow the user to modify selection states and/or directories should be sequenced before the InstallValidate action.

ActionData Messages

None.

Remarks

Typically, an earlier user-interface dialog box sequence should perform the same verification as the InstallValidate action whenever the user attempts to initiate the copying of files. This user interface dialog box sequence should present an Out of Disk Space dialog box if the volumes selected do not have enough space for the installation. The user-interface dialog boxes should be authored in a way to prevent the user from proceeding with the installation if there is insufficient disk-space. In the case of a quiet installation, there is no user interface and the InstallValidate action terminates the installation if there is insufficient disk space. The cause of the premature termination is recorded in the log file if logging is enabled.

An entry is added to an internal FilesInUse table if any file is overwritten or removed while it is open for execution or modification by any process during file costing. The FilesInUse table contains columns for the name and full path of the file. When the InstallValidate action executes, the installer queries the FilesInUse table for entries and determines the name of the process using the file. The InstallValidate action adds one record to the ListBox user-interface table for each unique process identified by this query. The record contains the following values in each column:

Property: FileInUseProcess
Value: <Name of process>
Text: <Text contained in the caption of main window of process>

The InstallValidate action then displays the FilesInUse dialog box. This dialog box displays the processes that must be shut down to avoid the requirement of rebooting the system to replace files in use.

The InstallValidate action queries the Dialog Table for an authored dialog with the reserved name FilesInUse dialog and displays it. This dialog box must contain a ListBox control that is tied to a property named FileInUseProcess. By convention, this dialog box has an Exit, Retry, or Ignore button, but this is up to the user-interface author. Each button should be tied to an EndDialog ControlEvent in the ControlEvent table. The InstallValidate action responds as follows to the value returned by the DoAction ControlEvent, as dictated by one of these EndDialog arguments associated with the button pushed by the user:

Retry: All values added to the ListBox table are cleared, and the entire file costing procedure is repeated, rechecking for files that are still in use. If one or more processes are still identified as using files to be overwritten or deleted, the process repeats; otherwise, InstallValidate returns control to the installer with a status of msiDoActionStatusSuccess.

Exit: The InstallValidate action immediately returns control to the installer with a status of msiDoActionStatusUserExit. This terminates the installation.

Any other return value: The InstallValidate action immediately returns control to the installer with a status of msiDoActionStatusSuccess. In this case, since one or more files are still in use, the subsequent InstallFiles and/or InstallAdminPackage actions must schedule the in-use file(s) to be replaced or deleted when the system is restarted.

If no dialog box named FilesInUse is found, or if the database has no ListBox table, InstallValidate exits silently without an error.

The semicolon is the list delimiter for transforms, sources, and patches and should not be used in these file names or paths.

Files marked read-only in a read-only location are never considered in use by the installer.

A default Out of disk space dialog box containing Abort and Retry buttons is presented to the user if the user interface level is basic.


IsolateComponents Action

The IsolateComponents action installs a copy of a component (commonly a shared DLL) into a private location for use by a specific application (typically an .exe). This isolates the application from other copies of the component that may be installed to a shared location on the computer. For more information, see Isolated Components.

The action refers to each record of the IsolatedComponent table and associates the files of the component listed in the Component_Shared field with the component listed in the Component_Application field. The installer installs the files of Component_Shared into the same directory as Component_Application. The installer generates a file in this directory, zero bytes in length, having the short filename name of the key file for Component_Application (typically this is the same file name as the .exe) appended with .local. The IsolatedComponent action does not affect the installation of Component_Application. Uninstalling Component_Application also removes the Component_Shared files and the .local file from the directory.

Sequence Restrictions

The IsolateComponents action can be used only in the InstallUISequence table and the InstallExecuteSequence table. This action must come after the CostInitialize action and before the CostFinalize action.

ActionData Messages

None.

Remarks

If the Condition column for the IsolateComponents action evaluates to True, or is left blank, the installer isolates all the components listed in the IsolatedComponent table. If the Condition column evaluates to False, the installer ignores the IsolatedComponent table and shares the components usual. The RedirectedDLLSupport property may be used to condition this action. For more information, see Using a Sequence Table.


LaunchConditions Action

The LaunchConditions action queries the LaunchCondition table and evaluates each conditional statement recorded there. If any of these conditional statements fail, an error message is displayed to the user and the installation is terminated.

Sequence Restrictions

The LaunchConditions action is optional. This action is normally the first in the sequence, but the AppSearch Action may be sequenced before the LaunchConditions action. If there are launch conditions that do not apply to all installation modes, the appropriate installation mode property should be used in a conditional expression in the appropriate sequence table.

ActionData Messages

None.


MigrateFeatureStates Action

The MigrateFeatureStates action is used during upgrading and when installing a new application over a related application. MigrateFeatureStates reads the feature states in the existing application and then sets these feature states in the pending installation. The method is only useful when the new feature tree has not greatly changed from the original.

MigrateFeatureStates action runs through each record of the Upgrade table in sequence and compares the upgrade code, product version, and language in each row to all products installed on the system. If MigrateFeatureStates action detects a correspondence, and if the msidbUpgradeAttributesMigrateFeatures bit flag is set in the Attributes column of the Upgrade table, the installer queries the existing feature states for the product and sets these states for the same features in the new application. The action only migrates the feature states if the Preselected property is not set.

Sequence Restrictions

The MigrateFeatureStates action should come immediately after the CostFinalize action. MigrateFeatureStates action must be sequenced in both the InstallUISequence table and the InstallExecuteSequence table.

ActionData Messages

MigrateFeatureSettings sends an action data message for each product.

Remarks

If more than one installed product shares a feature, the installation state for that feature may differ between products. MigrateFeatureState action uses the following order of precedence when migrating feature installation states: run local, run from source, advertised, and uninstalled. For example, installed product A may have feature Y as INSTALLSTATE_LOCAL and installed product B may have feature Y as INSTALLSTATE_ABSENT. If an upgrade installs product C and migrates the installation state of feature Y, MigrateFeatureState sets the installation state of feature Y in product C to INSTALLSTATE_LOCAL.

For more information about how to use the MigrateFeatureStates action for product upgrades, see Preparing an Application for Future Major Upgrades.


MoveFiles Action

The MoveFiles action locates existing files on the user's computer and moves or copies those files to a new location. The MoveFiles action queries the MoveFile table and moves files specified there if the component linked to the entries is specified to be install locally or is being run from source.

Sequence Restrictions

The MoveFiles action must come after the InstallValidate action and before the InstallFiles action.

ActionData Messages

Field | Description of action data
[1] | Identifier of moved file
[6] | Size of installed file in bytes
[9] | Identifier of directory holding moved file

Remarks

The MoveFiles table contain a column named "options" which specifies the source files to be moved or copied. A moved source file is deleted after it has been copied to a new location. For the exact syntax, see the MoveFile table.

The SourceFolder and DestFolder columns of the MoveFile table are property names whose values are expected to resolve to fully qualified paths. These properties can be any of the directory entries in the Directory table, any predefined folder property (FavoritesFolder, for example), or a property set by any entry in the AppSearch table. These properties may contain a full path containing the file name to a specific file. For example, the AppSearch table can be authored to search for a particular file and set a property to the full path to that file. In this example, the SourceName column in the MoveFile table can be left blank to indicate that the value in the SourceFolder property contains a full file path. The semicolon is the list delimiter for transforms, sources, and patches and should not be used in file names or paths.

The MoveFiles action does not act on entries in the MoveFile table in which either the SourceFolder or DestFolder property does not evaluate to a full path.

The MoveFiles action attempts to move or copy all files in the source directory that match the name given in the SourceName column of the MoveFiles table. The name in the SourceName column can include either the * or ? wildcards which allow a group of files to be moved or copied. For example, the SourceName column may contain an entry of "*.xls" and the MoveFiles action moves or copies every Microsoft® Excel workbook from the source directory to the destination.

The name to be given to the destination file can be specified in the DestName column of the MoveFile table. The destination file name retains the source file name if this column is left blank.

It is good practice to leave the DestName column of the MoveFile table blank if a wildcard is specified in the SourceName column. If a destination file name is specified in the DestName column and a wildcard is used in the SourceName column, the first source file that matches the wildcard criteria is given the specified destination name. All other moved or copied files will have the same name as the source file.

Files that are moved or copied by the MoveFiles action are not deleted when the product is uninstalled.


MsiPublishAssemblies Action

The MsiPublishAssemblies action manages the advertisement of common language runtime assemblies and Win32 assemblies that are being installed. The action queries the MsiAssembly table to determine which assemblies have features being advertised or installed to the global assembly cache and which assemblies have a parent component being advertised or installed to a location isolated for a particular application.

Enter the MsiPublishAssemblies action in the InstallExecuteSequence table or AdvtExecuteSequence table.

This action requires Windows Installer Version 1.5 or later versions.

Sequence Restrictions

The MsiPublishAssemblies action must come after the InstallInitialize action.

ActionData Messages

Field Description of action data

Remarks

For more information see Assemblies.

The MsiUnPublishAssemblies Action manages the advertisement of assemblies being removed.


MsiUnPublishAssemblies Action

The MsiUnPublishAssemblies action manages the advertisement of common language runtime assemblies and Win32 assemblies that are being removed. The action queries the MsiAssembly table to determine which assemblies have advertised or installed features being removed from the global assembly cache and which assemblies have an advertised or installed parent component being removed from a location isolated for a particular application.

Enter the MsiUnPublishAssemblies action in the InstallExecuteSequence table.

This action requires Windows Installer Version 1.5 or later versions.

Sequence Restrictions

The MsiUnPublishAssemblies action must come after the InstallInitialize action.

ActionData Messages

Field Description of action data

Remarks

For more information see Assemblies.

The MsiPublishAssemblies Action manages the advertisement of assemblies being advertised or installed.


PatchFiles Action

The PatchFiles action queries the Patch table to determine which patches are to be applied. The PatchFiles action also performs the byte-wise patching of the files.

Sequence Restrictions

If the file that is to be patched is not installed, the PatchFiles action must come after the InstallFiles action that installs the file. Previously installed files may be patched at any point in the action sequence. The DuplicateFiles Action must come after the PatchFiles action to prevent duplicating the unpatched version of the file.

ActionData Messages

Field | Description of action data
[1] | Identifier of patched file
[2] | Identifier of directory holding patched file
[3] | Size of patch in bytes


PreventInstall Action

The PreventInstall action blocks the pending installation of a product if both the property set by the Upgrade table operator and the property in the Property column of the Upgrade table are set.

Sequence Restrictions

The PreventInstall action must come after the FindRelatedProducts action.

ActionData Messages

None.

Remarks

If the product is already installed and the action should therefore not execute, use a conditional expression of "NOT Installed" in the condition column of the table.

For more information about using the PreventInstall action in product upgrades, see Preparing an Application for Future Major Upgrades.


ProcessComponents Action

The ProcessComponents action registers and unregisters components, their key paths, and the component clients. The ProcessComponents action queries the KeyPath column of the Component table to determine keypaths. This registration is used by MsiGetComponentPath to return the path of a component for a product client.

Sequence Restrictions

None.

ActionData Messages

For each component being registered.

Field | Description of action data
[1] | ProductId
[2] | ComponentId
[3] | The key path for the component.

For each component being unregistered.

Field | Description of action data
[1] | ProductId
[2] | ComponentId


PublishComponents Action

The PublishComponents action manages the advertisement of the components from the PublishComponent table.

Sequence Restrictions

None.

ActionData Messages

Field | Description of action data
[1] | GUID representing the component ID of an advertised feature
[2] | Qualifier of component ID

Remarks

The PublishComponents action publishes all of the components from the PublishComponents table that belong to features that have been selected for advertisement or installation.


PublishFeatures Action

The PublishFeatures action writes each feature's state into the system registry. The feature state may be either absent, advertised, or installed. The PublishFeatures action also writes the feature-component mapping into the system registry for each installed feature.

The PublishFeatures action queries the FeatureComponents table, Feature table, and Component table.

Sequence Restrictions

The PublishFeatures action must come before PublishProduct.

ActionData Messages

Field | Description of action data
[1] | Identifier of advertised feature

Remarks

The PublishFeatures action publishes the composition of all features that are selected to be advertised or installed.


PublishProduct Action

The PublishProduct action manages the advertisement of the product information with the system. This action publishes the product if the product is in advertise mode or if the MsiGetProductInfo function returns ERROR_INSTALL_PRODUCT for the product.

Sequence Restrictions

The PublishProduct action must come after the PublishFeatures action.

ActionData Messages

Field | Description of action data
[1] | Identifier of advertised product


RegisterClassInfo Action

The RegisterClassInfo action manages the registration of COM class information with the system. It uses the AppId table.

Sequence Restrictions

The RegisterClassInfo action must come after the InstallFiles action and the UnregisterClassInfo action.

The sequencing of the actions in the following group is restricted. If any subset of these actions occur together in a sequence table, they must have the same relative sequence order as shown below.

UnregisterClassInfo

UnregisterExtensionInfo

UnregisterProgIdInfo

UnregisterMIMEInfo

RegisterClassInfo

RegisterExtensionInfo

RegisterProgIdInfo

RegisterMIMEInfo

For example, RegisterClassInfo must come after UnregisterMIMEInfo in the sequence table.

ActionData Messages

Field 1 : Class ID of COM server

Field | Description of action data
[1] | GUID class identifier of the registered COM server

Remarks

If the system supports install-on-demand for OLE servers, RegisterClassInfo registers all COM classes in the Class table associated with a feature selected to be installed or advertised. Otherwise this action only registers the COM classes associated with a feature selected for installation.

See Also

OLEAdvtSupport property


RegisterComPlus Action

The RegisterComPlus action registers COM+ applications.

Sequence Restrictions

The RegisterComPlus action must follow the InstallFiles action and the UnregisterComPlus action.

ActionData Messages

Field | Description of action data
[1] | Application ID of the COM+ application.

Remarks

This action is not available with Windows Installer version 1.0.

See Also

Complus table, UnregisterComPlus action, How do I install a COM+ application with the Windows Installer?


RegisterExtensionInfo Action

The RegisterExtensionInfo action manages the registration of extension related information with the system.

Sequence Restrictions

The RegisterExtensionInfo action must come after the InstallFiles action and the UnregisterExtensionInfo action.

The sequencing of the actions in the following group is restricted. If any subset of these actions occur together in a sequence table, they must have the same relative sequence order as shown below.

UnregisterClassInfo

UnregisterExtensionInfo

UnregisterProgIdInfo

UnregisterMIMEInfo

RegisterClassInfo

RegisterExtensionInfo

RegisterProgIdInfo

RegisterMIMEInfo

For example, RegisterExtensionInfo must come after UnregisterMIMEInfo in the sequence table.

ActionData Messages

Field | Description of action data
[1] | Registered extension

Remarks

If the system supports install-on-demand for extension servers, RegisterExtensionInfo registers all extension servers in the Extension table associated with features set for installation or advertise. Otherwise this action only registers extension servers associated with features set to installation.

See Also

ShellAdvtSupport property


RegisterFonts Action

The RegisterFonts action registers installed fonts with the system. This action maps the font name in the FontTitle column of the Font table to the path of the font file installed.

Sequence Restrictions

The InstallFiles action must be called before calling the RegisterFonts action.

ActionData Messages

Field | Description of action data
[1] | Font File

Remarks

The RegisterFonts action is executed if the file specified in the File_ column of the Font table belongs to a component being installed.


RegisterMIMEInfo Action

The RegisterMIMEInfo action registers MIME-related registry information with the system.

Sequence Restrictions

The RegisterMIMEInfo action must come after the InstallFiles action, UnregisterMIMEInfo action, RegisterClassInfo action, and the RegisterExtensionInfo action.

The sequencing of the actions in the following group is restricted. If any subset of these actions occur together in a sequence table, they must have the same relative sequence order as shown below.

UnregisterClassInfo

UnregisterExtensionInfo

UnregisterProgIdInfo

UnregisterMIMEInfo

RegisterClassInfo

RegisterExtensionInfo

RegisterProgIdInfo

RegisterMIMEInfo

For example, RegisterMIMEInfo must come after UnregisterMIMEInfo in the sequence table.

ActionData Messages

Field | Description of action data
[1] | Identifier of registered MIME content type
[2] | Extension associated with MIME content type

Remarks

The RegisterMIMEInfo action registers all MIME information for servers from the MIME table for which the corresponding class server or extension server has been selected to be installed.


RegisterProduct Action

The RegisterProduct action registers the product information with the installer. Additionally, this action stores the installer database on the local computer.

The RegisterProduct action uses the ARPNOMODIFY and the ARPNOREMOVE properties. Setting ARPNOMODIFY removes the modify functionality of Add/Remove Programs in the Control Panel and the Programs wizard. Setting ARPNOREMOVE removes the remove functionality of Add/Remove Programs in the Control Panel and the Programs wizard.

Sequence Restrictions

None.

ActionData Messages

Field | Description of action data
[1] | Information about registered product

Remarks

The RegisterProduct action is not performed during an installation to an administrative installation point.


RegisterProgIdInfo Action

The RegisterProgIdInfo action manages the registration of OLE ProgId information with the system.

Sequence Restrictions

The RegisterProgIdInfo action must come after the InstallFiles action, UnregisterProgIdInfo action, RegisterClassInfo action action, and the RegisterExtensionInfo action.

The sequencing of the actions in the following group is restricted. If any subset of these actions occur together in a sequence table, they must have the same relative sequence order as shown below.

UnregisterClassInfo

UnregisterExtensionInfo

UnregisterProgIdInfo

UnregisterMIMEInfo

RegisterClassInfo

RegisterExtensionInfo

RegisterProgIdInfo

RegisterMIMEInfo

For example, RegisterProgIdInfo must come after RegisterExtensionInfo in the sequence table.

ActionData Messages

Field | Description of action data
[1] | Program identifier of registered program

Remarks

The RegisterProgIdInfo action registers all ProgId information for servers that are specified in the ProgId table and for which the corresponding class server or extension server has been selected to be installed.

See Also

Class table, Extension table


RegisterTypeLibraries Action

The RegisterTypeLibraries action registers type libraries with the system. This action is applied to each file referred to in the TypeLib table that is scheduled for install.

Sequence Restrictions

The RegisterTypeLibraries action must come after the InstallFiles action.

ActionData Messages

Field | Description of action data
[1] | GUID of registered type library


RegisterUser Action

The RegisterUser action registers the user information with the installer to identify the user of a product.

Sequence Restrictions

None.

ActionData Messages

Field | Description of action data
[1] | Registered user information

Remarks

The RegisterUser action is not performed during an administrative installation. If the product identifier entered by the user has not been validated by the ValidateProductID action, the ProductID property is not set and this action does nothing.

See Also

USERNAME property, COMPANYNAME property, ProductID property


RemoveDuplicateFiles Action

The RemoveDuplicateFiles action deletes files installed by the DuplicateFiles action.

Sequence Restrictions

The RemoveDuplicateFiles action must occur after the InstallValidate action and before the InstallFiles action.

ActionData Messages

Field | Description of action data
[1] | Identifier of removed file
[9] | Identifier of directory holding removed file

Remarks

To delete a file duplicated with the DuplicateFiles action using the RemoveDuplicateFiles action, the component associated with the file's entry in the DuplicateFile table must be selected for removal.

Use the DestFolder column of the DuplicateFile table to specify the property name whose value identifies the destination folder.


RemoveEnvironmentStrings Action

The RemoveEnvironmentStrings action modifies the values of environment variables.

Note that environment variables do not change for the installation in progress when either the WriteEnvironmentStrings action or RemoveEnvironmentStrings action are run. On Windows NT and Windows 2000, this information is stored in the registry and a message is sent to notify the system of changes when the installation completes. A new process, or another process that checks for these messages, will use the new environment variables. On Windows 95 and Windows 98, this information is stored in the autoexec.bat file, and do not affect the system until a system reboot.

The installer runs the WriteEnvironmentStrings action only during the installation or reinstallation of a component, and runs the RemoveEnvironmentStrings action only during the removal of a component.

Values are written or removed based on the selection of primary actions and modifiers. These are described below in the ActionData Messages section. Note that depending upon the action specified, WriteEnvironmentStrings may remove variables, and RemoveEnvironmentStrings may add them based on the authoring of the Environment table.

Sequence Restrictions

The InstallValidate action must be executed before the RemoveEnvironmentStrings action. Because the WriteEnvironmentStrings action and RemoveEnvironmentStrings action are never both applied during the installation or removal of a component, their relative sequence is not restricted.

ActionData Messages

Field | Description of action data
[1] | Name of the environment variable to modify.
[2] | The environment variable value.
[3] | This is a field of bit flags that specify the action to be performed. Include only one bit for a primary action. There may be more than one modifier bit included in this field. See the following bit flag descriptions.

Bit value | Description of primary actions
0x1 | Set. Sets the value of the environment variable in all cases. If this bit is combined with an Append or Prefix modifier bit, the action adds the value to any existing value in the variable.
0x2 | Set. Sets the value if the variable is absent. If this bit is combined with an Append or Prefix modifier bit, the action adds the value to any existing value in the variable.
0x4 | Remove. Removes the value from the variable. If this bit is combined with an Append or Prefix modifier bit, the value is removed from the existing string, if the value exists.

Bit value | Description of modifier
0x20000000 | If this bit is set, actions are applied to the machine environment variables. If this bit is not set, actions are applied to the user's environment variables. This bit is ignored on Windows 95 and Windows 98.
0x40000000 | Append. This bit is optional. Do not set both the Append and Prefix modifiers.
0x80000000 | Prefix. This bit is optional. Do not set both the Append and Prefix modifiers.


RemoveExistingProducts Action

The RemoveExistingProducts runs through the product codes listed in the ActionProperty column of the Upgrade table and removes the products in sequence by invoking nested installations. At each nested installation the installer sets the ProductCode property to the product code and the REMOVE property to the value in the Remove field of the Upgrade table. If the Remove field is blank, its value defaults to ALL and the installer removes the entire product.

The installer only runs RemoveExistingProducts during the initial installation and not during maintenance installations.

Sequence Restrictions

The RemoveExistingProducts action must be scheduled in the action sequence in one of the following locations.

  1. Between the InstallValidate action the InstallInitialize action. In this case, the installer removes the old applications entirely before installing the new applications. This is an inefficient placement for the action because all reused files have to be recopied.
  2. After the InstallInitialize action and before any actions that generate execution script.
  3. Between the InstallExecute action, or the InstallExecuteAgain action, and the InstallFinalize action. Generally the last three actions are scheduled right after one another: InstallExecute, RemoveExistingProducts, and InstallFinalize. In this case the updated files are installed first and then the old files are removed. However, if the removal of the old application fails, then the installer rolls back both the removal of the old application and the install of the new application.
  4. After the InstallFinalize action. This is the most efficient placement for the action. In this case, the installer updates files before removing the old applications. Only the files being updated get installed during the installation. If the removal of the old application fails, then the installer only rolls back the uninstallation of the old application.

ActionData Messages

Field | Description of action data
[1] | Removed product


RemoveFiles Action

The RemoveFiles action removes files previously installed by the InstallFiles action. Each of these files is gated by a link to an entry in the Component table. Only those files with components resolved to either the msiInstallSateAbsent state or the msiInstallStateLocal state if the component is installed locally, are removed.

Sequence Restrictions

The InstallValidate action must be called before calling RemoveFiles. If an InstallFiles action is used, it must appear after RemoveFiles.

ActionData Messages

Field | Description of action data
[1] | Identifier of removed file
[9] | Identifier of directory holding removed file

Remarks

The RemoveFile table can be omitted from the installer database if there are no miscellaneous files to remove.

The RemoveFiles action can also remove author-specified files that are not installed by the InstallFiles action. These files are specified in the RemoveFile table. Each of these files is gated by a link to an entry in the Component table. Those files whose components are resolved to any active Action state (that is, not in the Off or Null state) are removed if the file exists in the specified directory. The removal of files specified in the RemoveFile table is attempted when the linked component is first installed, during a reinstall, and again when the linked component is removed.

The RemoveFiles action can also remove folders. An empty folder is removed if the value in the FileName column of the RemoveFile table is null.

When removing previously installed files, the RemoveFiles action queries the same fields in the same tables as those queried by the InstallFiles action with the exception that the Media table is not used by the RemoveFiles action.

The target file name can be specified in localized text in the FileName column of the RemoveFile table.


RemoveFolders Action

The RemoveFolders action removes any folders linked to components set to be removed or run from source. These folders are removed only if they are empty. If a folder is removed, it is unregistered with the appropriate component identifier.

Sequence Restrictions

The RemoveFolders action must come after the RemoveFiles action or any action that may remove files from folders.

ActionData Messages

Field | Description of action data
[1] | Identifier of removed folder

Remarks

The installer does not automatically remove the folders created by the CreateFolders action during an uninstall of the application. The installer must be instructed to remove these folders by authoring the RemoveFolders action into the action sequence.

To specify the name and location of the folder, use the Directory_ column of the CreateFolder table. Each folder name in the CreateFolder table is assumed to be a property defining the folder location.

To specify the component owning the folder, use the ComponentId column of the Component table.


RemoveIniValues Action

The RemoveIniValues action removes .ini file information specified for removal in the RemoveIniFile table if the component is set to be installed locally or run-from-source. The RemoveIniValues action removes .ini file information that has been associated with a component in the IniFile table. This action also removes .ini file information if the information was written by the WriteIniValues action and the component is scheduled to be uninstalled.

Sequence Restrictions

The InstallValidate action must be called before the RemoveIniValues action. If a WriteIniValues action is used in the sequence, it must appear after RemoveIniValues.

ActionData Messages

Field | Description of action data
[1] | Identifier of .ini file
[2] | .ini file key below section
[3] | Item removed form .ini file
[4] | Value removed from .ini file

See Also

RemoveIniFile table, IniFile table, WriteIniValues action, InstallValidate


RemoveODBC Action

The RemoveODBC action removes the data sources, translators, and drivers listed for removal during the installation. This action queries the ODBCDataSource table, ODBCTranslator table, and ODBCDriver table for each data source, translator, or driver scheduled for removal.

Sequence Restrictions

None.

ActionData Messages

For each driver installed.

Field | Description of action data
[1] | Driver description. The ODBC driver key.
[2] | ComponentId

For each translator installed.

Field | Description of action data
[1] | Driver description. The ODBC driver key.
[2] | ComponentId

For each data source installed.

Field | Description of action data
[1] | Driver description. The ODBC driver key.
[2] | ComponentId
[3] | Registration: SQL_REMOVE_DSN or SQL_REMOVE_SYS_DSN

Remarks

If both the ODBC usage count and the file usage count become zero, the file is removed. Registration is dependent on ODBC usage counts and file removal is based on shared DLLs key reference counts.


RemoveRegistryValues Action

The RemoveRegistryValues action can only remove values from the system registry that have been authored into the Registry table or the RemoveRegistry table. This action removes a registry value that has been authored into the Registry table if the associated component was installed locally or as run from source and is now set to be uninstalled. This action removes a registry value that has been authored into the RemoveRegistry table if the associated component is set to be installed locally or as run from source.

Sequence Restrictions

The InstallValidate action must be called before calling RemoveRegistryValues. If a WriteRegistryValues action is used, it must come after RemoveRegistryValues. RemoveRegistryValues must come before UnregisterMIMEInfo or UnregisterProgIDInfo.

ActionData Messages

Field | Description of action data
[1] | Registry path to key of removed registry value
[2] | Formatted string of name of removed registry value

Remarks

To remove a registry value, record the value in the Value column of the Registry table. If the WriteRegistryValues action has attached REG_MULTI_SZ strings to the value in the Registry table, then the RemoveRegistryValues action removes only those strings from the registry value.


RemoveShortcuts Action

The RemoveShortcuts action manages the removal of an advertised shortcut whose feature is selected for uninstall or a non-advertised shortcut whose component is selected for uninstall. For more information, see the Shortcut Table.

Sequence Restrictions

The RemoveShortcuts action must come after the InstallFiles action and before the CreateShortcuts action.

ActionData Messages

Field | Description of action data
[1] | Identifier of removed shortcut


ResolveSource Action

The ResolveSource action determines the location of the source and sets the SourceDir property if the source has not been resolved yet.

Sequence Restrictions

The ResolveSource action must come after the CostInitialize action.

ActionData Messages

None.

Remarks

The ResolveSource action must be called before using the SourceDir property in any expression. It must also be called before attempting to retrieve the value of the SourceDir property using MsiGetProperty. The ResolveSource action should not be executed when the source is unavailable, as it may be when uninstalling the application.

See Also

Source Resiliency


RMCCPSearch Action

The RMCCPSearch action uses file signatures to validate that qualifying products are installed on a system before an upgrade installation is performed.

Sequence Restrictions

None.

ActionData Messages

None.

Remarks

The RMCCPSearch action requires the CCP_DRIVE property to be set to the root path on the removable volume that has the installation for any of the qualifying products.

Each file signature in the CCPSearch table is searched for under the path referred to by the CCP_DRIVE property using the DrLocator table. The absence of the signature from the Signature table denotes a directory. If any signature is determined to exist, the RMCCPSearch action terminates.

See Also

CCPSearch table


ScheduleReboot Action

Insert the ScheduleReboot action into the action sequence to prompt the user for a reboot of the system at the end of the installation. Use the ForceReboot action to prompt for a reboot during the installation.

If the installation has a user interface, the installer displays a message box and button at the end of the installation asking whether the user wants to reboot the system. The user must respond to this prompt before completing the installation. If the installation has no user interface, the system automatically reboots at the end.

If the installer determines that a reboot is necessary it automatically prompts the user to reboot at the end of the installation, whether or not there are any ForceReboot or ScheduleReboot actions in the sequence. For example, the installer automatically prompts for a reboot if it needs to replace any files that are in use during the installation.

You can suppress certain prompts for reboots by setting the REBOOT property.

See Also

System Reboots

Sequence Restrictions

None.

ActionData Messages

None.

Remarks

For example, this action can be used to force the installer to prompt for a reboot after installing drivers that require a reboot. If the installer attempts to replace files that are in use, it automatically prompts the user to reboot even if ScheduleReboot has not been used.

The ScheduleReboot action is typically placed at the end of the sequence, but it can be inserted at any point in the sequence.


SelfRegModules Action

The SelfRegModules action processes all modules listed in the SelfReg table and registers all installed modules with the system. The installer does not self-register EXE files.

Sequence Restrictions

The InstallValidate action must be called before calling the SelfRegModules action. If an InstallFiles action is used, it must appear before the SelfRegModules action in the sequence.

ActionData Messages

Field | Description of action data
[1] | Identifier of registered module file
[2] | Identifier of folder holding registered module file

Remarks

The SelfRegModules action attempts to call the DllRegisterServer function of the module scheduled to be registered. This action runs with elevated privileges when the installation is being run with elevated privileges, such as during a per-machine installation. During a per-user installation the installer runs this action with user privileges.

Note that you cannot specify the order in which the installer registers self-registering DLLs by using the SelfUnRegModules action.

See Also

Specifying the Order of Self Registration


SelfUnregModules Action

The SelfUnregModules action unregisters all modules listed in the SelfReg table that are scheduled to be uninstalled. The installer does not self-register EXE files.

Sequence Restrictions

The InstallValidate action must appear before the SelfUnregModules action in the sequence. If a SelfRegModules action is used it must appear after the SelfUnregModules action in the sequence. If a RemoveFiles action is used it must appear after the SelfUnregModules action in the sequence.

ActionData Messages

Field | Description of action data
[1] | Identifier of unregistered module file
[2] | Identifier of folder holding unregistered module file

Remarks

The SelfUnregModules action attempts to call the DllUnregisterServer function of the module that is to be unregistered. This action runs with elevated privileges when the installation is being run with elevated privileges, such as during a per-machine installation. During a per-user installation, the installer runs this action with user privileges.

Note that you cannot specify the order in which the installer unregisters self-registering DLLs by using the SelfUnRegModules action.

See Also

Specifying the Order of Self Registration


SEQUENCE Action

The SEQUENCE action sorts and runs in sequence the actions in a table.

The SEQUENCE property defines the table used by this action. The table must have the same schema as the InstallExecuteSequence table. The table must have an Action, Condition, and Sequence column.

Sequence Restrictions

None.

ActionData Messages

None.


SetODBCFolders Action

The SetODBCFolders action checks for existing ODBC drivers on the system and sets the target directory of each new driver to the location of an existing driver.

Sequence Restrictions

The SetODBCFolders action must come after the CostFinalize action and before the InstallValidate action.

ActionData Messages

Field | Description of action data
[1] | Driver description. The ODBC driver key.
[2] | Original folder location of the new driver.
[3] | New folder location for the new driver. This is the location of an existing driver.

Remarks

This action places a new driver into the same directory as the existing driver being replaced. The SetODBCFolders action uses the Directory table to set the locations of existing drivers that are to be replaced.


StartServices Action

The StartServices action starts system services. This action queries the ServiceControl table.

Sequence Restrictions

The services actions must be used in the following sequence.

StopServices

DeleteServices

Any of the following actions: InstallFiles, RemoveFiles, DuplicateFiles, MoveFiles, PatchFiles, and RemoveDuplicateFiles actions.

InstallServices action

StartServices

It is recommended that StartServices be sequenced just before the RegisterUser action.

ActionData Messages

Field | Description of action data
[1] | Service display name.
[2] | Service name

Remarks

This action requires that the user be an administrator or have elevated privileges with permission to control services or that the application be part of a managed installation.


StopServices Action

The StopServices action stops system services. This action queries the ServiceControl table.

Sequence Restrictions

The services actions must be used in the following sequence.

StopServices action

DeleteServices

Any of the following actions: InstallFiles, RemoveFiles, DuplicateFiles, MoveFiles, PatchFiles, and RemoveDuplicateFiles actions.

InstallServices action

StartServices

ActionData Messages

Field | Description of action data
[1] | Service display name.
[2] | Service name

Remarks

This action requires that the user be an administrator or have elevated privileges with permission to control services or that the application be part of a managed installation.


UnpublishComponents Action

The UnpublishComponents action manages the unadvertisement of components listed in the PublishComponent table. These are components that may be faulted in by other products. This action removes information about published components from the PublishComponent table for which the corresponding feature is currently selected to be uninstalled.

Sequence Restrictions

None.

ActionData Messages

Field | Description of action data
[1] | GUID representing the component ID of an advertised feature
[2] | Qualifier of component ID

ActionData Messages

None.


UnpublishFeatures Action

When an entire product is uninstalled, the UnpublishFeatures action removes selection-state and feature-component mapping information from the system registry. This action queries the FeatureComponents Table.

Sequence Restrictions

None.

ActionData Messages

Field | Description of action data
[1] | Identifier of unadvertised feature


UnregisterClassInfo Action

The UnregisterClassInfo action manages the removal of COM class information from the system registry. It uses the AppId table.

Sequence Restrictions

The UnregisterClassInfo action must come after the InstallFiles action and before the RegisterClassInfo action.

RemoveRegistryValues must come before UnregisterClassInfo in the sequence.

The sequencing of the actions in the following group is restricted. If any subset of these actions occur together in a sequence table, they must have the same relative sequence order as shown below.

UnregisterClassInfo

UnregisterExtensionInfo

UnregisterProgIdInfo

UnregisterMIMEInfo

RegisterClassInfo Action

RegisterExtensionInfo

RegisterProgIdInfo

RegisterMIMEInfo

For example, RegisterExtensionInfo must come before UnregisterClassInfo in the sequence table.

ActionData Messages

Field | Description of action data
[1] | GUID of unregistered COM class

Remarks

The installer sets the OLEAdvtSupport property to true when the current user's system has been upgraded to work with install-on-demand through COM. If the system does not support install-on-demand through COM, UnregisterClassInfo removes all COM classes listed in the Class table associated with either uninstalled features or features installed as advertised from the system registry. Otherwise this action removes only te COM classes associated with features selected to be uninstalled from the system registry.


UnregisterComPlus Action

The UnregisterComPlus action removes COM+ applications from the registry.

Sequence Restrictions

The RegisterComPlus action must follow the InstallFiles action and the UnregisterComPlus action.

ActionData Messages

Field | Description of action data
[1] | Application ID of the COM+ application being removed.

Remarks

This action is not available with Windows Installer version 1.0.

See Also

RegisterComPlus action and Complus table, How do I install a COM+ application with the Windows Installer?


UnregisterExtensionInfo Action

The UnregisterExtensionInfo action manages the removal of extension-related information from the system registry.

Sequence Restrictions

The UnregisterExtensionInfo action must come after the InstallFiles action and before the RegisterExtensionInfo action.

RemoveRegistryValues must come before UnregisterExtensionInfo in the sequence.

The sequencing of the actions in the following group is restricted. If any subset of these actions occur together in a sequence table, they must have the same relative sequence order as shown below.

UnregisterClassInfo

UnregisterExtensionInfo

UnregisterProgIdInfo

UnregisterMIMEInfo

RegisterClassInfo

RegisterExtensionInfo

RegisterProgIdInfo

RegisterMIMEInfo

For example, UnregisterExtensionInfo must come before UnRegisterProgIDInfo in the sequence table.

ActionData Messages

Field | Description of action data
[1] | Removed extension

Remarks

If the system does not support the install-on-demand of extension servers, UnregisterExtensionInfo removes all extension servers in the Extension table associated with either an uninstalled feature or a feature installed as advertised from the registry. Otherwise, this action removes the extension servers associated with a feature that is selected to be removed from the registry.

See Also

ShellAdvtSupport Property


UnregisterFonts Action

The UnregisterFonts action removes registration information about installed fonts from the system.

Sequence Restrictions

The RemoveFiles action must be called after UnregisterFonts.

ActionData Messages

Field | Description of action data
[1] | Font File

Remarks

The UnregisterFonts action is executed if the file specified in the File_ column of the Font table belongs to a component being uninstalled.


UnregisterMIMEInfo Action

The UnregisterMIMEInfo action unregisters MIME-related registry information from the system. The action unregisters MIME information for servers from the MIME table for which the corresponding feature is currently selected to be uninstalled.

Sequence Restrictions

The UnregisterMIMEInfo action must come after the InstallFiles action, UnregisterClassInfo action, UnregisterExtensionInfo action, and before the RegisterMIMEInfo action.

RemoveRegistryValues must come before UnregisterMIMEInfo in the sequence.

The sequencing of the actions in the following group is restricted. If any subset of these actions occur together in a sequence table, they must have the same relative sequence order as shown below.

UnregisterClassInfo

UnregisterExtensionInfo

UnregisterProgIdInfo

UnregisterMIMEInfo

RegisterClassInfo

RegisterExtensionInfo

RegisterProgIdInfo

RegisterMIMEInfo

For example, UnregisterMIMEInfo must come before RegisterExtensionInfo in the sequence table.

ActionData Messages

Field | Description of action data
[1] | Identifier of unregistered MIME content type
[2] | Extension associated with MIME content type


UnregisterProgIdInfo Action

The UnregisterProgIdInfo action manages the unregistration of OLE ProgId information with the system.

Sequence Restrictions

The UnregisterProgIdInfo action must come after the InstallFiles action, UnregisterClassInfo action, UnregisterExtensioninfo action, and before the RegisterProgIdInfo action.

RemoveRegistryValues must come before UnregisterProgIdInfo in the sequence.

The sequencing of the actions in the following group is restricted. If any subset of these actions occur together in a sequence table, they must have the same relative sequence order as shown below.

UnregisterClassInfo

UnregisterExtensionInfo

UnregisterProgIdInfo

UnregisterMIMEInfo

RegisterClassInfo

RegisterExtensionInfo

RegisterProgIdInfo

RegisterMIMEInfo

For example, UnregisterProgIdInfo must come before UnregisterMIMEInfo in the sequence table.

ActionData Messages

Field | Description of action data
[1] | Program identifier of registered program

Remarks

The UnregisterProgIdInfo action removes ProgId information from the registry (ProgId Table) for features that are connected to the extension information (Extension table) or the Class information (Class table) and are currently selected to be uninstalled.


UnregisterTypeLibraries Action

The UnregisterTypeLibraries action unregisters type libraries from the system. This action is applied to each file listed in the TypeLib table that is triggered to be uninstalled.

Sequence Restrictions

The UnregisterTypeLibraries action must come before the RemoveFiles action.

ActionData Messages

Field | Description of action data
[1] | GUID of unregistered type library


ValidateProductID Action

The ValidateProductID action sets the ProductID property to the full product identifier.

Sequence Restrictions

This action must be sequenced before the user-interface wizard in the InstallUISequence table and before the RegisterUser action in the InstallExecuteSequence table.

ActionData Messages

None.

Remarks

If the product identifier has already been validated successfully, the ValidateProductID action does nothing.

The ValidateProductID action always returns a success, whether or not the product identifier is valid, so that the product identifier can be entered on the command line the first time the product is run.

The product identifier can be validated without having the user reenter this information by setting the PIDKEY property on the command line or by using a transform. The display of the dialog box requesting the user to enter the product identifier can then be made conditional upon the presence of the ProductID property, which is set when the PIDKEY property is validated.


WriteEnvironmentStrings Action

The WriteEnvironmentStrings action modifies the values of environment variables.

Note that environment variables do not change for the installation in progress when either the WriteEnvironmentStrings action or RemoveEnvironmentStrings action are run. On Windows NT and Windows 2000, this information is stored in the registry and a message is sent to notify the system of changes when the installation completes. A new process, or another process that checks for these messages, will use the new environment variables. On Windows 95 and Windows 98, this information is stored in the autoexec.bat file, and do not affect the system until a system reboot.

The installer runs the WriteEnvironmentStrings action only during the installation or reinstallation of a component, and runs the RemoveEnvironmentStrings action only during the removal of a component.

Values are written or removed based on the selection of primary actions and modifiers. These are described below in the ActionData Messages section. Note that depending on the action specified, WriteEnvironmentStrings may remove variables, and RemoveEnvironmentStrings may add them based on the authoring of the Environment table.

Sequence Restrictions

The InstallValidate action must be executed before the RemoveEnvironmentStrings action. Because the WriteEnvironmentStrings action and RemoveEnvironmentStrings action are never both applied during an install or removal of a component, their relative sequence is not restricted.

ActionData Messages

Field | Description of action data
[1] | Name of the environment variable to modify.
[2] | The environment variable value.
[3] | This is a field of bit flags that specify the action to be performed. Include only one bit for a primary action. There may be more than one modifier bit included in this field. See the bit flag descriptions below.

Bit Value | Description of primary actions
0x1 | Set. Sets the value of the environment variable in all cases. If this bit is combined with an Append or Prefix modifier bit, the action adds the value to any existing value in the variable.
0x2 | Set. Sets the value if the variable is absent. If this bit is combined with an Append or Prefix modifier bit, the action adds the value to any existing value in the variable.
0x4 | Remove. Removes the value from the variable. If this bit is combined with an Append or Prefix modifier bit, the value is removed from the existing string, if the value exists.

Bit Value | Description of modifier
0x20000000 | If this bit is set, actions are applied to the machine environment variables. If this bit is not set, actions are applied to the user's environment variables. This bit is ignored on Windows 95 and Windows 98.
0x40000000 | Append. This bit is optional. Do not set both the Append and Prefix modifiers.
0x80000000 | Prefix. This bit is optional. Do not set both the Append and Prefix modifiers.


WriteIniValues Action

The WriteIniValues action writes the .ini file information that the application needs written to its .ini files. The writing of this information is gated by the Component table. An .ini value is written if the corresponding component has been set to be installed either locally or run from source.

Sequence Restrictions

The InstallValidate action must come before the WriteIniValues action. If there is a RemoveIniValues action in the sequence, then it must come before the WriteIniValues action.

ActionData Messages

Field | Description of action data
[1] | Identifier of .ini file
[2] | .ini file key below section
[3] | Item removed form .ini file
[4] | Value removed from .ini file

See Also

IniFile table


WriteRegistryValues Action

The WriteRegistryValues action sets up an application's registry information. The registry information is gated by the Component table. A registry value is written to the registry if the corresponding component has been set to be installed either locally or as run from source. For more information, see Registry table.

Sequence Restrictions

The InstallValidate action must come before the WriteRegistryValues action. If there is a RemoveRegistryValues action, then it must come before the WriteRegistryValues action.

ActionData Messages

Field | Description of action data
[1] | Path to registry key of value written to registry
[2] | Formatted text string name of value written to registry
[3] | Formatted text string of value written to registry


Custom Actions

The Microsoft® Windows® Installer provides many built-in actions for performing the installation process. For a list of these actions, see the Standard Actions Reference.

Standard actions are sufficient to execute an installation in most cases. However, there are situations where the developer of an installation package finds it necessary to write a custom action. For example:

  • You want to launch an executable during the installation that is installed on the user's machine or that is being installed with the application.
  • You want to call special functions during an installation that are defined in a dynamic-link library (DLL).
  • You want to use functions written in the development languages Microsoft Visual Basic® Scripting Edition or Microsoft JScript® literal script text during an installation.
  • You want to defer the execution of some actions until the time when the installation script is being executed.
  • You want to add time and progress information to a ProgressBar control and a TimeRemaining Text control.
  • You want to run a nested installation.

The follow sections describe custom actions and how to incorporate them into an installation package.

  • About Custom Actions
  • Using Custom Actions
  • Custom Action Reference
  • Summary List of All Custom Action Types


About Custom Actions

Although standard actions are sufficient to execute an installation in most cases, custom actions enable the author of an installation package to extend the capabilities of standard actions by including executables, dynamic-link libraries, and script. Custom actions cannot be used in the sequence tables used for advertisement, the AdvtUISequence table and the AdvtExecuteSequence table.

The following sections provide more information about custom actions.

Custom Action Sources

Synchronous and Asynchronous Custom Actions

Rollback Custom Actions

Commit Custom Actions

Deferred Execution Custom Actions

Executable Files

Dynamic-Link Libraries

Scripts

Formatted Text Custom Actions

Error Message Custom Actions

Nested Installation Actions

Custom Action Security


Custom Action Sources

A custom action source can exist in several different forms. The following table lists the types of custom actions that can have each form of source. See the topic for the basic custom action type for more information.

Custom action source | Associated custom action types
Custom action stored in the Binary table. | Custom Action Type 1, Custom Action Type 2, Custom Action Type 5, Custom Action Type 6
Custom action copied during installation. | Custom Action Type 17, Custom Action Type 18, Custom Action Type 19, Custom Action Type 21, Custom Action Type 22
Custom action referencing a directory. | Custom Action Type 34
Custom action referencing a property. | Custom Action Type 50, Custom Action Type 53, Custom Action Type 54
Custom action stored as literal script code in database table. | Custom Action Type 37, Custom Action Type 38

See Summary List of All Custom Action Types for a summary of all types of custom actions and how sources are specified in the CustomAction table.

See Also

About Custom Actions, Using Custom Actions, Custom Action Reference


Synchronous and Asynchronous Custom Actions

The Windows Installer processes custom actions as a separate thread from the main installation. During synchronous execution of a custom action, the installer waits for the thread of the custom action to complete before continuing the main installation. During asynchronous execution, the installer runs the custom action simultaneously as the current installation continues. Authors of custom actions must therefore be aware of any asynchronous threads that may be making changes to the installation database between function calls.

In particular, calls to MsiGetTargetPath and MsiSetTargetPath should be avoided in asynchronous custom actions. Instead use MsiGetProperty to obtain a target path. Bulk database operations such as import, export, and transform operations should be avoided in any type of custom action.

Option flags can be set in the Type field of the CustomAction table to specify that the main and custom action threads run synchronously or asynchronously. See Custom Action Return Processing Options.

The installer can only execute nested installations and rollback custom actions as synchronous custom actions.

For more information, see Nested Installation Actions and Rollback Custom Actions.


Rollback Custom Actions

When the installer processes the installation script, it simultaneously generates a rollback script. In addition to the rollback script, the installer saves a copy of every file it deletes during the installation. These files are kept in a hidden system directory. Once the installation is complete, the rollback script and the saved files are deleted. If an installation is unsuccessful, the installer attempts to rollback the changes made during the installation and restore the original state of the computer.

Although custom actions that schedule system operations by inserting rows into database table are reversed by a rollback of the installation, custom actions that change the system directly, or that issue commands to other system services, cannot always be reversed by a rollback. A rollback custom action is an action that the installer executes only during an installation rollback, and its purpose is to reverse a custom action that has made changes to the system.

A rollback custom action is a type of deferred execution custom action, because its execution is deferred when it is invoked during the installation sequence. It differs from a regular deferred custom action in that it is only executed during a rollback. A rollback custom action must always precede the deferred custom action it rolls back in the action sequence. A rollback custom action should also handle the case where the deferred custom action is interrupted in the middle of execution. For example, if the user were to press the Cancel button while the custom action was executing.

Note that Rollback Custom Actions cannot run asychronously. See Synchronous and Asynchronous Custom Actions.

The complement to a rollback custom action is a commit custom action. The installer executes a commit custom action during the installation sequence, copies the custom action into the rollback script, but does not execute the action during rollback.

When the installer runs a rollback custom action, the only mode parameter it will set is MSIRUNMODE_ROLLBACK. See MsiGetMode for a description of the run mode parameters.

A rollback custom action can be specified by adding an option flag to the Type field of the CustomAction table. See Custom Action In-Script Execution Options for the option flag designating a rollback custom action.

Rollback and commit custom actions do not run when rollback is disabled. If a package author requires these types of custom actions for proper installation, they should use the RollbackDisabled property in a condition that prevents the installation from continuing when rollback is disabled. For information on how to disable rollback see Rollback Installation (Windows Installer).


Commit Custom Actions

Commit Custom actions are executed upon successful completion of the installation script. If the InstallFinalize action is successful, the installer will then run any existing Commit Custom actions. The only mode parameter the installer sets in this case is MSIRUNMODE_COMMIT. See MsiGetMode for a description of the run mode parameters.

A commit custom action does not execute during the rollback of the installation. A commit custom action is the complement to a rollback custom action and can be used with rollback custom actions to reverse custom actions that make changes directly to the system.

A commit custom action can be specified by adding an option flag to the Type field of the CustomAction table. See Custom Action In-Script Execution Options for the option flag designating a commit custom action.

Rollback and commit custom actions do not run when rollback is disabled. If a package author requires these types of custom actions for proper installation, they should use the RollbackDisabled Property in a condition that prevents the installation from continuing when rollback is disabled.


Deferred Execution Custom Actions

The purpose of a deferred execution custom action is to delay the execution of a system change to the time when the installation script is executed. This differs from a regular custom action, or a standard action, in which the installer executes the action immediately upon encountering it in a sequence table or in a call to MsiDoAction. A deferred execution custom action enables a package author to specify system operations at a particular point within the execution of the installation script.

The installer does not execute a deferred execution custom action at the time the installation sequence is processed. Instead the installer writes the custom action into the installation script. The only mode parameter the installer sets in this case is MSIRUNMODE_SCHEDULED. See MsiGetMode for a description of the run mode parameters.

A deferred execution custom action must be scheduled in the execute sequence table within the section that performs script generation. Deferred execution custom actions must come after InstallInitialize and come before InstallFinalize in the action sequence.

Custom actions that set properties, feature states, component states, or target directories, or that schedule system operations by inserting rows into sequence tables, can in many cases use immediate execution safely. However, custom actions that change the system directly, or call another system service, must be deferred to the time when the installation script is executed. See Synchronous and Asynchronous Custom Actions for more information about potential clashes between their custom actions and the main installation thread.

Because the installation script can be executed outside of the installation session in which it was written, the session may no longer exist during execution of the installation script. This means that the session handle and property data set during the installation sequence is not available to a deferred execution custom action. A custom action that calls a dynamic-link library (DLL) requires a handle to the installation session. Therefore if this is also a deferred execution custom action, the action must obtain its context information as described in Obtaining Context Information for Deferred Execution Custom Actions.

See Also

Custom Action In-Script Execution Options, Custom Action Reference


Executable Files

A custom action can launch an executable file that is stored on the user's machine or contained inside the installation package.

The following types of custom action launch an executable file.

Custom action type | Description
Custom Action Type 2 | EXE file stored in a Binary table stream.
Custom Action Type 18 | EXE file that is installed with a product.
Custom Action Type 50 | EXE file having a path specified by a property value.
Custom Action Type 34 | EXE file having a path referencing a directory.

See the section Summary List of All Custom Action Types for a summary of all types of custom actions and how they are encoded into the CustomAction table.


Dynamic-Link Libraries

A custom action can call a function defined in a dynamic-link library (DLL) written in C or C++. The DLL can exist as a file installed during the current installation or as a temporary binary stream originating from the Binary table of the installation database.

Note that any called functions, including custom actions in DLLs, must specify the __stdcall calling convention.

The following types of custom actions call a dynamic-link library.

Custom action type | Description
Custom Action Type 1 | DLL file stored in a Binary table stream.
Custom Action Type 17 | DLL file that is installed with a product.

Note To use COM you need to call CoInitializeEx in the custom action. Do not quit if you find that the thread has already been initialized. For example, the thread is initialized in a per-machine installation but not in a per-user installation.

See Summary List of All Custom Action Types for a summary of all types of custom actions and how they are encoded into the CustomAction table.


Scripts

A custom action can call functions that are in written in VBScript of JScript (i.e. JavaScript or ECMA 262). The installer does not provide the script engine. Authors wishing to make use of a scripting language during installation must therefore ensure that the appropriate scripting engine is available.

Windows Installer does not support JScript 1.0.

The following basic custom action types call functions written in script.

Custom action type | Description
Custom Action Type 5 | JScript file stored in a Binary table stream.
Custom Action Type 21 | JScript file that is installed with a product.
Custom Action Type 53 | JScript text specified by a property value.
Custom Action Type 37 | JScript text stored in this sequence table.
Custom Action Type 6 | VBScript file stored in a Binary table stream.
Custom Action Type 22 | VBScript file that is installed with a product.
Custom Action Type 54 | VBScript text specified by a property value.
Custom Action Type 38 | VBScript text stored in this sequence table.

See the section Summary List of All Custom Action Types for a summary of all types of custom actions and how they are encoded into the CustomAction table.


Formatted Text Custom Actions

This type of custom action sets a property or an install directory from a formatted text string. The parameters in this string may be properties, environment variables, file paths, or the directory paths of components. This is useful for passing information to subsequent custom actions.

The following basic custom action types set a property or directory. For more information, see the particular Custom Action Type.

Custom action type | Description
Custom Action Type 51 | Set a property with a formatted text string.
Custom Action Type 35 | Set a directory with a formatted text string.

See the section Summary List of All Custom Action Types for a summary of all types of custom actions and how they are encoded into the CustomAction table.


Error Message Custom Actions

This type of custom action displays a specified error message and returns failure, terminating the installation. The error message to be displayed can be supplied as a string or as an index into the Error table.

Custom action type | Description
Custom Action Type 19 | Terminate the installation and display an error message.

See the section Summary List of All Custom Action Types for a summary of how to encode each of the custom action types into the CustomAction table.


Nested Installation Actions

Nested installations are not available with Windows Installer version 1.0.

A nested installation action installs another Windows Installer package during a currently running installation. A nested installation is added to a package by authoring a nested installation action into the CustomAction table and scheduling this custom action into the sequence tables. The Target field of the CustomAction table contains a string of public property settings used by the nested installation. The Source field of the CustomAction table identifies the nested package.

The type of nested installation action is specified in the Type field of the CustomAction table. Depending upon the custom action type, the package for the nested application can reside in a sub-storage of the main package, as a file at a location specified by a property, or as an advertised application on the user's machine. The following types of custom actions perform a nested installation.

Custom action type | Description
Custom Action Type 7 | Nested installation of a product residing in the installation package.
Custom Action Type 23 | Nested installation of an installer package within the current source tree.
Custom Action Type 39 | Nested installation of an advertised installer package.

A nested installation shares the same user interface and logging settings as the main installation.

The use of deferred execution with nested installation actions is unnecessary because the installer combines rollback information from the nested and main installations. This means that all changes are reversed upon a rollback installation.

The return values for nested installation actions are the same as for other custom actions. See Custom Action Return Values.

Standard or custom actions that specify an automatic reboot of the system, or request the user to reboot, can also perform reboot or request from within a nested installation.

Once the installer begins a nested installation, it locks out all other all other installations until the nested installation is complete and before continuing the main installation. The installer can only execute nested installations as synchronous custom actions. See Synchronous and Asynchronous Custom Actions. The option flags described in Custom Action Return Processing Options must be set to none (+0) or msidbCustomActionTypeContinue (+64).

A nested installation action can install an application to be run locally, to run from source, to be reinstalled, or to be removed in the same manner as when using MsiInstallProduct for a regular installation. To specify the type of installation, pass either the ADDLOCAL, ADDSOURCE, REINSTALL, or REMOVE property to the nested installation action.

There is no method for querying a package for its cost. This makes the costing of a nested installations difficult. Rows must be added to the ReserveCost table to indicate the folders and worst-case costs of the component associated with the nested install.

The only Custom Action Return Processing Options available with nested installation actions are none (+0) or msidbCustomActionTypeContinue (+64).

Note that a parent installation cannot call its own package as a nested installation action.

Note that if a per-machine installation attempts to run a per-user nested installation, the installer registers the parent installation as per-user by default. This can cause the installer to incorrectly remove the application because the installer attempts to uninstall the application per-machine when it is actually registered as per-user. To force the state of a nested installation to track the state of its parent installation, enter ALLUSERS=[ALLUSERS] in the Target column of the CustomAction table. In this case, the nested installation is per-machine if the parent is per-machine, and the nested installation is per-user if the parent is per-user.

Developers should note the following warnings when authoring nested installations.

  • Nested installations cannot share components:
  • An administrative installation cannot also contain a nested installation.
  • Patching and upgrading may not work with nested installations.
  • The installer may not properly cost a nested installation.
  • Integrated progress bars cannot be used with nested installations.
  • Resources that are to be advertised cannot be installed by the nested installation.

See Also

ALLUSERS, How do I specify a per-user or per-machine installation?


Custom Action Security

The installer runs custom actions with user privileges by default in order to limit the access of custom actions to the system. The installer may run custom actions with elevated privileges if a managed application is being installed or if the system policy has been specified for elevated privileges.

Windows 2000

For Microsoft® Windows® 2000, if the msidbCustomActionTypeNoImpersonate bit is not set for a custom action, the installer runs the custom action with user-level privileges. For more information, see Custom Action In-Script Execution Options.

If the msidbCustomActionTypeNoImpersonate bit is set and a managed application is being installed with administrator permission, the installer may run the custom action with elevated privileges. However, if a user attempts to install the managed application without administrator permission, the installer runs the application with user level privileges regardless of whether msidbCustomActionTypeNoImpersonate is set.

Note that a custom action may run with system privileges even when the msidbCustomActionTypeNoImpersonate bit is not set. This may occur if an administrator installs the application for all users on a computer using Windows 2000 Terminal Server. This may also occur if the installation is invoked when there is no user context. For example, if there is no currently logged-on user during an installation invoked by Windows 2000 Application Deployment.

Windows NT

For Microsoft Windows NT® 4.0, if the msidbCustomActionTypeNoImpersonate bit is not set for a custom action, the installer runs the custom action with user level privileges. For more information, see Custom Action In-Script Execution Options.

Note that a custom action may run with system privileges in cases where the installation is invoked without an associated user context, even when the msidbCustomActionTypeNoImpersonate bit is not set.

If the msidbCustomActionTypeNoImpersonate bit is set, and the AlwaysInstallElevated policies are set, the installer may run the custom action with elevated privileges.


Using Custom Actions

The following sections describe using custom actions.

  • Invoking Custom Actions
  • Sequencing Custom Actions
  • Obtaining Context Information for Deferred Execution Custom Actions
  • Adding Custom Actions to the ProgressBar
  • Debugging Custom Actions
  • Determining User Interface Level from a Custom Action
  • Uninstalling Custom Actions
  • Returning Error Messages from Custom Actions
  • Attempting to set a restore point from a Custom Action
  • How do I access the current installer session from inside a custom action?
  • How do I access another database or session from inside a custom action?
  • How do I use a custom action to launch an installed file at the end of the installation?
  • How do I use a custom action to create user accounts on the local computer?

For an overview of custom actions, see About Custom Actions.

For more information about encoding custom actions into the CustomAction table, see Custom Action Reference.

For a summary of custom actions and how they are encoded into the CustomAction table, see Summary List of All Custom Action Types.


Invoking Custom Actions

Custom actions are invoked in the same manner as standard actions, either by explicit invocation or during the execution of a sequence table. There are two methods for calling actions:

  • You call the specified action directly with the MsiDoAction function.
  • A top-level action calls the sequence table containing the custom action. For more information about scheduling a custom action in a sequence table, see Sequencing Custom Actions.

When the installer obtains an action name from the MsiDoAction function, or from a sequence table, it first searches for a standard action of that name. If it cannot find the standard action, then the installer queries the CustomAction table to check if the specified action is a custom action. If the specified action is not a custom action, then the installer queries the Dialog table for a dialog box.


Sequencing Custom Actions

Custom actions are scheduled in sequence tables in the same way as standard actions.

To schedule a custom action in a sequence table

  1. Enter the custom action name (which is the primary key of the CustomAction table) into the Action column of the sequence table.
  2. Enter the custom action's sequence relative to the other actions in the table into the Sequence column of the sequence table. For more information about sequence tables, see Using a Sequence Table.
  3. To conditionally skip the action, enter a conditional expression into the Condition column of the sequence table. The installer skips this action if the expression evaluates to FALSE.

As in the case of standard actions, custom actions that are scheduled in the InstallUISequence or AdminUISequence are run only if the internal user interface is set to the Full level. The UI level is set by using the MsiSetInternalUI function.

Standard and custom actions scheduled in the InstallExecuteSequence, AdminExecuteSequence, or AdvtExecuteSequence tables do not make system changes. Instead the installer queues up execution records in a script for subsequent execution during the install service. If there is no install service, then the actions scheduled in these tables are run in the same context as the UI sequence.

If the installer server is not registered, as is the case of Windows 95 and Windows 98, then the custom actions are executed on the client side. If the server is registered and using the full UI mode, then the custom actions are run on the server side.

If using full UI with the server, the initial actions prior to the InstallValidate action are run on the client to allow full interaction. Execution is then switched to the server which repeats those actions and runs the script execution actions. This is followed by a return to the client for the final actions.

Note that if a product is removed by setting its top feature to absent, the REMOVE property may not equal "ALL" until after the InstallValidate action. This means that any custom action that depends on REMOVE="ALL" must be sequenced after the InstallValidate action. A custom action may check REMOVE to determine if a product has been set to be completely uninstalled.

Custom actions that reference an installed file as their source, such as Custom Action Type 17 (DLL), Custom Action Type 18 (EXE), Custom Action Type 21 (JScript), and Custom Action Type 22 (VBScript), must adhere to the following sequencing restrictions.

  • The custom action must be sequenced after the CostFinalize action so that the path to the referenced file can be resolved.
  • If the source file is not already installed on the computer, deferred (in-script) custom actions must be sequenced after the InstallFiles action.
  • If the source file is not already installed on the computer, non-deferred custom actions must be sequenced after the InstallFinalize action.


Obtaining Context Information for Deferred Execution Custom Actions

Because the installation script can be executed outside of the installation session in which it was written, the session may no longer exist during execution of the installation script. This means that the session handle and property data set during the installation sequence are not available to a deferred execution custom action. Functions that do not require a session handle can be accessed from a custom action. Functions that require a session handle, however, must use one of a few methods that can retrieve context information, or property values that are needed during script execution must be written into the installation script.

A dynamic-link library (DLL) custom action requires a handle to the installation session. If this is also a deferred execution custom action, the custom action must use one of the following methods to retrieve its context.

Method name | Description
MsiGetProperty | Supports a limited set of properties when used with deferred execution custom actions: the CustomActionData and ProductCode properties.
MsiGetMode | When called from deferred execution custom actions, commit custom actions, or rollback custom actions, MsiGetMode returns True or False when requested to check the mode parameters MSIRUNMODE_SCHEDULED, MSIRUNMODE_COMMIT, or MSIRUNMODE_ROLLBACK. Requests to check any other run mode parameters from a deferred, commit, or rollback custom action returns False.
MsiGetLanguage | The numeric language ID for the current product.
MsiProcessMessage | Processes error or progress messages from the custom action

A custom action that is written in JScript or VBScript requires the install Session object. This is of the type Session Object and the installer attaches it to the script with the name "Session". Because the Session object may not exist during an installation rollback, a deferred custom action written in script must use one of the following methods or properties of the Session object to retrieve its context.

Name | Description
Mode Property | Returns True for MSIRUNMODE_SCHEDULED only.
Property Property (Session Object) | Returns the CustomActionData or ProductCode properties.
Language Property (Session Object) | Returns numeric language ID of the install session.
Message Method | Can be called to handle errors and progress.
Installer Property | Returns the parent object, which is used for non-session functions such as registry access and installer configuration management.

Property values that are set at the time the installation sequence are processed into script can be unavailable at the time of script execution. Only the following limited set of properties are always accessible to custom actions during script execution.

Property name | Description
CustomActionData | Value at time custom action is processed in sequence table.
ProductCode | Unique code for the product, a GUID string.

If other property data is required by the deferred execution custom action, then their values must be stored in the installation script. You can do this using a second custom action.

To write the value of a property into the installation script for use during the execution of a deferred execution custom action

  1. Insert a small custom action into the installation sequence that sets the property of interest to a property having the same name as the deferred execution custom action. For example, if the primary key for the deferred execution custom action is "MyAction" set a property named "MyAction" to the property X which you need to retrieve. You must set the "MyAction" property in the installation sequence before the "MyAction" custom action. Although any type of custom action can set the context data, the simplest method is to use a property assignment custom action (for example Custom Action Type 51).
  2. At the time when the installation sequence is processed, the installer will write the value of property X into the execution script as the value of the property CustomActionData.


Adding Custom Actions to the ProgressBar

Custom Actions can add time and progress information to a ProgressBar control. For more information about creating an action display dialog box, see Authoring a Progress Bar Control.

A custom action must add ticks to the total tick count during the acquisition and script generation phase of the installation. An immediate execution custom action must be scheduled in the sequence table after any standard action that generates script records, such as:

InstallValidate action
InstallInitialize action
ProcessComponents action

The following example code fragment is used in the immediate execution custom action to add the ticks to the total tick count.

MSIHANDLE hEngine = NULL;
UINT iResult = MsiOpenPackage("c:\MyPackage.msi", &hEngine);
// Error handling code
PMSIHANDLE hRec = MsiCreateRecord(3);
MsiRecordSetInteger(hrec, 1, 3);        // ProgressAddition subclass
MsiRecordSetInteger(hrec, 2, 24000);    // Add 24000 ticks to the current progress total
iResult = MsiProcessMessage(hInstall, INSTALLMESSAGE_Progress, hRec);
// Error handling code

A deferred execution custom action is required to send the individual tick amounts to the ProgressBar control during installation. The code required to accomplish this is similar to the prior example with the exception that the MsiRecordSetInteger function would be used to set the correct field of the record created with the MsiCreateRecord function to the ProgressReport value.

The amount of ticks reported by this deferred execution custom action must be equal to the number of ticks added to the total tick count by the immediate execution action or the time remaining reported by the TimeRemaining text control is inaccurate.

To add a custom action to the progress bar

  1. Decide how to describe the progress of the custom action in terms of reference items as they are installed on the target media. For example, a custom action that installs registry keys can display a progress message and update the progress bar each time the installer writes one registry key.
  2. In the following steps you need to refer to the progress bar's final total length, and its change in length in terms of arbitrary units called 'ticks'. Base the tick units in your custom actions on the number of bytes installed on the target media. Usually, a change in progress bar length of one tick corresponds to the installation of a one byte of files.
  3. Each update of the control by the installer changes the length of the progress bar by a constant increment. Specify or calculate the number of ticks in one such increment. For example, if the installer installs approximately 13400 bytes when it writes one registry key, specify that an increment is 13400 ticks. Usually this information can be coded into the custom action.
  4. Specify or calculate the total number of ticks the custom action adds to the length of the progress bar. The installer needs this information at the time it generates the installation script to estimate the final total length of the progress bar. The number of ticks added by the custom action is usually calculated as: (bytes installed per reference item) x (number of reference items). For our example, if the custom action writes 20 registry keys, the installer installs approximately 268000 bytes and the installer must increase the estimate of the final total length of the progress bar by 268000 ticks. If the installer is to calculate this dynamically, the custom action must contain code that is immediately executed during script generation.
  5. Separate your custom action into three parts that run during the script generation, execution, and rollback phases of the installation.
  6. In the part of the custom action that runs during a rollback, insert code for any changes the custom action needs to make during a rollback.
  7. In the part of the custom action that runs at the time the installer is generates the installation script, tell the installer to increase the estimate of the final total length of the progress bar by the total number of ticks in the custom action. You may also include any code here needed to calculate the total number of ticks added by the custom action.
  8. In the part of the custom action that runs during the execution phase of the installation, set up appropriate message text and templates that will inform the user about what the custom action is doing and the installer how to update the progress bar control. For example, inform the installer to move the progress bar forward one increment and send an explicit progress message with each update. There is usually a loop in this part of the custom action that installs something. For example, with each pass through this loop, the installer can install one reference item such as a registry key and update the progress bar control.

The following sample shows how a custom action can be added to the progress bar. The sample installs 1000 reference items that are each approximately 10000 bytes in size. The installer updates the message and indicator displayed by the progress bar control each time it installs a reference item.

#include <windows.h>
#include <msiquery.h>

    // Specify how many ticks there are in one length increment. This
    // is usually hard coded into the custom action and a change in
    // length of one tick usually corresponds to the installation of
    // one byte of files. For this sample, a length change of one
    // increment is 10000 ticks and corresponds to 10000 bytes.

const UINT iTickIncrement = 10000;

    // Specify or calculate the total number of ticks the custom
    // action adds to the final total length of the progress bar.
    // This would usually be calculated as: (bytes per item
    // installed) x (number of items). For this sample:
    // (10000) x (1000) is hard coded in as a constant.

const UINT iTotalTicks = 10000000;

UINT __stdcall CAProgress(MSIHANDLE hInstall)
{
    PMSIHANDLE hRec = MsiCreateRecord(3);
    PMSIHANDLE hProgressRec = MsiCreateRecord(3);

    // Tell the installer to check the installation state and execute
    // the code needed during the rollback, acquisition, or
    // execution phases of the installation.

  if (MsiGetMode(hInstall,MSIRUNMODE_ROLLBACK))
  {
    // Installer is rolling back the installation. Additional code
    // could be inserted here to enable the custom action to do
    // something during an installation rollback.

    return ERROR_SUCCESS;
  }

  if (!MsiGetMode(hInstall,MSIRUNMODE_SCHEDULED))
  {
    // Installer is generating the installation script of the custom
    // action. Additional code could be inserted here to enable the
    // installer to calculate the value of iTotalTicks during
    // script generation.

    // Tell the installer to increase the value of the final total
    // length of the progress bar by the total number of ticks in the
    // custom action.

    MsiRecordSetInteger(hRec,1,3);
    MsiRecordSetInteger(hRec,2,iTotalTicks);
    MsiRecordSetInteger(hRec,3,0);
    UINT iResult = MsiProcessMessage(hInstall, INSTALLMESSAGE_PROGRESS, hRec);
    return ERROR_SUCCESS;
  }
  else
  {
    // Installer is executing the installation script. Set up a
    // record specifying appropriate templates and text for messages
    // that will inform the user about what the custom action is
    // doing. Tell the installer to use this template and text in
    // progress messages.

    MsiRecordSetString(hRec,1,TEXT("Progress Custom Action"));
    MsiRecordSetString(hRec,2,TEXT("Incrementing the Progress Bar..."));
    MsiRecordSetString(hRec,3,TEXT("incrementing tick [1] of [2]"));
    UINT iResult = MsiProcessMessage(hInstall, INSTALLMESSAGE_ACTIONSTART, hRec);

    // Tell the installer to use explicit progress messages.

    MsiRecordSetInteger(hRec,1,1);
    MsiRecordSetInteger(hRec,2,1);
    MsiRecordSetInteger(hRec,3,0);
    iResult = MsiProcessMessage(hInstall, INSTALLMESSAGE_PROGRESS, hRec);

    // Specify that an update of the progress bar's position in this
    // case means to move it forward by one increment.

    MsiRecordSetInteger(hProgressRec,1,2);
    MsiRecordSetInteger(hProgressRec,2,iTickIncrement);
    MsiRecordSetInteger(hProgressRec,3,0);

    // The following loop sets up the record needed by the progress
    // messages and tells the installer to send a message to update
    // the progress bar.

    MsiRecordSetInteger(hRec,2,iTotalTicks);
    for( int i = 0; i<iTotalTicks; i+=iTickIncrement)
    {
      MsiRecordSetInteger(hRec,1,i);
      iResult = MsiProcessMessage(hInstall, INSTALLMESSAGE_ACTIONDATA, hRec);
      iResult = MsiProcessMessage(hInstall, INSTALLMESSAGE_PROGRESS, hProgressRec);

    // A real custom action would have code here that does a part of
    // the installation. For this sample, code that install 10000
    // bytes of files.

      Sleep(0);
    }

    return ERROR_SUCCESS;
  }
}


Debugging Custom Actions

To enable the debugging of a custom action, set the environment variable MsiBreak to the name of the designated action, which is case-sensitive, the same as it appears in the CustomAction and sequence tables. For DLL custom actions, a user breakpoint is called just prior to the entry point call. If the current session is not running under a debugger, the standard exception dialog box is invoked with an option to debug. This brings up the debugger that is registered for JIT debugging (to enable MSDEV for this, under Options, select Just-in-time debugging). Single step a few times and you will be inside the custom action code.

To enable source-level debugging, the PDB file must be available, either at the original build location for the DLL, or in the directory where the DLL is executing. Custom actions stored in the Binary table are saved to a new temporary file and executed from the system TEMP directory. The temporary file name begins with MSI. This separate file is created to prevent conflict with other temp files. The PDB should be copied to the temp directory under the same name as the new custom action file. A separate thread is created to call the custom action to support asynchronous execution, to provide cleanup after the action is called, and to provide recovery in the case of an exception during execution. The mechanism is similar with EXE custom actions, except that the debug break occurs just prior to the CreateProcess call. You cannot step into the EXE code, and you cannot attach the debugger to the process until it is running. Debugging custom actions that are executing in the service requires the debugger to be attached to the service process (MsiExec.exe) ahead of time.

Starting with Windows Installer version 1.5, the installer adds debugging information for custom action scripts to the installation log file. For example the following:

There is a problem with this Windows Installer package. A script
required for this install to complete could not be run. Contact your
support personnel or package vendor.  {Custom action [2] script error
[3], [4]: [5] Line [6], Column [7], [8] }


Determining User Interface Level from a Custom Action

A custom action in a UI sequence table or an external executable may need the current user interface level of the installation. For example, a custom action that has a dialog box should only display the dialog when the user interface level is Full UI or Reduced UI, but not display the dialog if the user interface level is Basic UI or None. It is recommended that custom actions not use the UI level as a condition for sending error messages to the installer because this can interfere with logging and external messages.

To determine the user interface level from within a custom action, the action can call MsiSetInternalUI with the following arguments.

MsiSetInternalUI(INSTALLUILEVEL_NOCHANGE,0)

The return value of the function is the UI level originally requested. Note that the current UI level may have changed from this value during processing of the installation, such as if the LIMITUI property was set. If running in the installation service the function's return value is INSTALLUILEVEL_DEFAULT.

It may be possible to determine the current UI level by calling MsiSetInternalUI and checking the UILevel property rather than the return value. The value of this property takes into account the effect of LIMITUI and running in the service.


Uninstalling Custom Actions

Developers of installation packages that make use of custom actions must determine in each case how to condition the custom action to work correctly when the package is uninstalled. It is up to the package author to decide whether to condition the custom action to run on uninstall, not to run on uninstall, or to run an alternate custom action on uninstall.

See Also

Conditional Statement Syntax, Using Properties in Conditional Statements


Returning Error Messages from Custom Actions

This section describes how to send messages from custom actions that actually perform a part of the installation by calling a dynamic link library or script. Note that Custom Action Type 19 only sends a specified error message, returns failure, and then terminates the installation. CustomAction Type 19 cannot perform any part of the installation.

To send an error message from a custom action that uses a dynamic-link library, have the custom action call MsiProcessMessage. Note that custom actions launched by a DoAction ControlEvent cannot send messages with MsiProcessMessage. See Sending Messages to Windows Installer Using MsiProcessMessage.

To display an error message from within a custom action using a DLL

  1. The custom action should call MsiProcessMessage and pass in the parameters hInstall, eMessageType, and hRecord. The handle to the installation, hInstall, may be provided to the custom action as described in How do I access the current installer session from inside a custom action? or from MsiOpenProduct or MsiOpenPackage.
  2. The parameter eMessageType should specify one of the message types as listed in MsiProcessMessage.
  3. The hRecord parameter of the MsiProcessMessage function depends upon the message type. See Sending Messages to Windows Installer Using MsiProcessMessage. If the message contains formatted data, enter the message into the Error table using the formatting described in Formatted.

To send an error message from a custom action that uses Scripts, the custom action may call the Message method of the Session Object.

To display an error message from within a custom action using script

  1. The custom action should call Message method of the Session Object and pass in the parameters kind and record.
  2. The parameter kind should specify one of the message types listed in Message method.
  3. The record parameter of the Method method depends upon the message type. If the message contains formatted data, enter the message into the Error table using the formatting described in Formatted.

Custom actions using Executable Files cannot send a message by calling MsiProcessMessage or the Message method because they cannot get a handle to the installation.

See Also

Custom Action Return Values


Attempting to Set a Restore Point from a Custom Action

Custom actions must not call SRSetRestorePoint because this may result in a restore entry point being written into the middle of a Windows Installer installation.


How do I access the current installer session from inside a custom action?

Non-deferred custom actions that call dynamic-link libraries or scriptsmay access a running installation to query or modify the attributes of the current installation session. Only one Session object can exist for each process and custom action scripts must not attempt to create another session.

Note that custom actions can only add, modify, or remove temporary rows, columns, or tables from a database. Custom actions cannot modify persistent data in a database, such as data that is a part of the database stored on disk.

Dynamic-Link Libraries

To access a running installation, custom actions calling dynamic-link libraries (DLLs) are passed a handle of the type MSIHANDLE for the current session as the only argument to the DLL entry point named in the Target column of the CustomAction table. Because the installer provides this handle, the custom action should not close it. For example, to receive the handle hInstall from the installer, the custom action function would be declared as follows.

__stdcall CustomAction(MSIHANDLE hInstall)

For read-only access to the current database obtain the database handle by calling MsiGetActiveDatabase. For more information, see Obtaining a Database Handle.

Scripts

Custom actions written in VBScript or JScript can access the current installation session using the Session Object. The installer creates a Session object named "Session" that references the current installation. For read-only access to the current database use the Database property of the Session object.

Because a script is run from the context of the Session object, it is not always necessary to fully qualify properties and methods. Note that when using VBScript, the Me reference can replace the Session object. For example, the following three line are equivalent.

Session.SetInstallLevel 1
Me.SetInstallLevel 1
SetInstallLevel 1

Executable Files

You cannot access the current installer session from custom actions that call executable files launched with a command line, for example Custom Action Type 2 and Custom Action Type 18.

Deferred Execution Custom Actions

You cannot access the current the installation session or all property data from a deferred execution custom action. For more information, see Obtaining Context Information for Deferred Execution Custom Actions.

See Also

How do I access another database or session from inside a custom action?


How do I access another database or session from inside a custom action?

You cannot access an installer session from a custom action that is not the current installation session. Custom actions are limited to working with only the active database of the session and no other databases. The following Windows Installer Database Functions must not be called from a custom action because they require a handle to a database that is not the database of the current installation session:

MsiDatabaseMerge
MsiCreateTransformSummaryInfo
MsiDatabaseApplyTransform
MsiDatabaseCommit
MsiDatabaseExport
MsiDatabaseGenerateTransform
MsiDatabaseImport
MsiEnableUIPreview
MsiGetDatabaseState

See Also

How do I access the current installer session from inside a custom action?


How do I use a custom action to launch an installed file at the end of the installation?

The following example illustrates how to launch an HTML file at the end of an installation. The installer installs the component containing the file and then publishes a control event at the end of the installation to run a custom action that opens the file. This approach may be used to launch a help tutorial at the end of the first installation of an application.

The sample must meet the following specifications.

  • The installer executes the custom action only if the full UI level is used to install the application.
  • The installer executes the custom action only if the component containing the HTML file is installed to run locally on the computer.
  • The custom action only runs at first installation of the application
  • The installation does not fail if the custom action fails.

The sample includes a hypothetical component named Tutorial that controls at least one resource, a file named tutorial.htm. The identifier for this file in the File column of the File Table is Tutorial. The following discussion assumes that you have already created the resources required by Tutorial and have made all the necessary entries in the Feature, Component, File, Directory, and FeatureComponents tables to install this component. For an example of how to author the database to install components see An Installation Example.

The following sections demonstrate how to create the required custom action and add them to the installation package.

  • Authoring the Launch Custom Action
  • Adding Launch to the CustomAction and Binary Tables
  • Adding a Control Event at the End of the Installation to Run Launch

Continue to Authoring the Launch Custom Action.


Authoring the Launch Custom Action

The source code for a sample custom action named Launch, which meets the sample specifications, is provided by the Windows Installer SDK as the file tutorial.cpp. This custom action makes use of MsiFormatRecord to format a string containing properties. The property [#FileKey] resolves to the full path of the HTML file. Use the source file to create the file Launch.dll. The entry point to this DLL is LaunchTutorial.

The sample custom action Launch calls a DLL written in C++ and is generated from a temporary binary stream. Custom actions of this type include the base type constants msidbCustomActionTypeDll and msidbCustomActionTypeBinaryData, which give a base numeric type equal to 1. See Custom Action Type 1. Because the specifications require that the installation continue if the custom action fails, Launch also includes the optional constant msidbCustomActionTypeContinue, which is 64. See Custom Action Return Processing Options. The total numeric type of Launch is 65.

Continue to Adding Launch to the CustomAction and Binary Tables.


Adding Launch to the CustomAction and Binary Tables

Add a record to the CustomAction table for the Launch custom action. Enter the custom action's name in the Action column of the CustomAction table. Enter the total numeric type for Launch, 65, into the Type column of the Custom action table. The Source column of the CustomAction table specifies a key into the record of the Binary Table that contains the binary data for the DLL. Enter Launch.dll into the Source column of the CustomAction table. The entry point specified in the Target field of the CustomAction table must match that exported from the DLL. Enter LaunchTutorial into the Target column of the CustomAction table.

CustomAction Table

Action | Type | Source | Target
Launch | 65 | Launch.dll | LaunchTutorial

Add Launch.dll you created from tutorial.cpp as a binary stream to the Binary table.

Binary Table

Name | Data
Launch.dll | {binary data added for DLL}

Continue to Adding a Control Event at the End of the Installation to Run Launch.


Adding a Control Event at the End of the Installation to Run Launch

The installer runs the sample's installation wizard sequence only if the full UI level is used to install the application. The last dialog of the sample dialog sequence is an Exit Dialog named ExitDialog. When a user interacts with the OK button on ExitDialog this first publishes an EndDialog ControlEvent that returns control to the installer. The control then publishes a DoAction ControlEvent that runs the Launch custom action. Each control event requires a record in the ControlEvent table. See ControlEvent Overview.

ControlEvent Table

Dialog | Control_ | Event | Argument | Condition | Ordering
ExitDialog | OK | EndDialog | Return | 1 | 1
ExitDialog | OK | DoAction | Launch | NOT Installed AND $Tutorial=3 | 2

The condition on the DoAction control ensures the custom action only runs during the first installation of the application and that it is being installed locally. The phrase $Tutorial=3 means the action state of Tutorial is set to local. See Conditional Statement Syntax.

This completes the sample.


How do I use a custom action to create user accounts on the local computer?

This sample demonstrates how to use custom actions to create user accounts on the local computer when installing a component. Removal of the component removes the local user accounts created by the custom action. Several custom actions are demonstrated including deferred execution custom actions and rollback custom actions.

The sample meets the following specifications.

  • The installation creates user accounts only if running Windows NT or Windows 2000.
  • The installation creates user accounts only if the component is being installed to run locally. Note that this precludes creating user accounts during the repair or reinstallation of the component.
  • The installer removes the accounts when the component is removed.
  • User account information is read from a custom table in the installation database and is not hard-coded into the custom action code.
  • Because the creation or removal of user accounts requires elevated privileges, some of the custom actions must be capable of making changes to the system that require elevated privileges. These custom actions must be deferred custom actions that run when in the execution script.
  • Each account has a rollback custom action to ensure the account is removed upon rollback of the component's installation. Note that this does not include the rollback of an account deletion during the removal of the component.
  • Custom actions send ActionData messages for each account that is created or removed. Note this does not include providing progress messages for the progress bar.
  • Custom actions report an error if an account cannot be created.

The sample includes a hypothetical component named TestAccount. The discussion in the following sections assumes that you have already created the resources required by TestAccount and have authored the Feature, Component, File, Directory, and FeatureComponents tables in the sample database required to install this component. For an example of how to author these database tables to install a component see An Installation Example.

The following sections demonstrate how to create the required custom actions and add them to the installation package.

  • Authoring the Custom Actions
  • Adding a Custom CustomUserAccounts Table
  • Authoring the CustomAction Table
  • Authoring the ActionText and Error Tables
  • Authoring the InstallExecuteSequence Table

Continue to Authoring the Custom Actions.


Authoring the Custom Actions

The table below lists the five custom actions used to meet the sample specifications: ProcessAccounts, UninstallAccounts, CreateAccounts, RemoveAccounts, and RollbackAccounts. All of these custom actions are in dynamic-link libraries stored in the Binary Table. The C++ source code for the dynamic-link libraries containing the sample custom actions are provided in the Windows Installer SDK. ProcessAccounts and UninstallAccounts are in the file process.cpp. CreateAccount is in the file create.cpp. RemoveAccount and RollbackAccount are in the file remove.cpp. These source files can be used to create the files process.dll, create.dll, and remove.dll.

Because the creation or removal of a user account requires elevated privileges, deferred execution custom actions that run in the context of the system must be used to create, remove, or rollback user accounts. The immediate execution custom actions, ProcessAccounts and UninstallAccounts, generate the deferred custom actions that create, remove, or rollback user accounts: CreateAccount, RemoveAccount, and RollbackAccount.

Because deferred custom actions cannot read information in database tables, ProcessAccounts and UninstallUserAccouts must set a CustomActionData property to pass the information in the UserAccounts table to the deferred custom actions as described in Obtaining Context Information for Deferred Execution Custom Actions. When the installer runs the execution script, the deferred custom actions handles user accounts according to the information in the CustomActionData property.

Because all the custom actions are in dynamic-link libraries stored in the Binary table, they all include the constants msidbCustomActionTypeDll and msidbCustomActionTypeBinaryData in their base numeric type. ProcessAccounts and UninstallAccounts are examples of pure Custom Action Type 1. For information on other custom action types see the Summary List of All Custom Action Types.

CreateAccount and RemoveAccount are deferred execution custom actions that do not allow services to impersonate particular users. These custom actions include the constants msidbCustomActionTypeInScript and msidbCustomActionTypeNoImpersonate to specify these custom action in-script execution options.

RollbackAccount is a rollback custom action that only removes user accounts during a rollback installation. RollbackAccount includes the constants msidbCustomActionTypeInScript and msidbCustomActionTypeRollback to specify these custom action in-script execution options.

Custom action | DLL entry point | Custom action type
ProcessAccounts | ProcessUserAccounts in Process.dll. | msidbCustomActionTypeDll + msidbCustomActionTypeBinaryData = 1
UninstallAccounts | UninstallUserAccounts in Process.dll. | msidbCustomActionTypeDll + msidbCustomActionTypeBinaryData = 1
CreateAccount | CreateUserAccount in Create.dll. | msidbCustomActionTypeDll + msidbCustomActionTypeBinaryData + msidbCustomActionTypeInScript + msidbCustomActionTypeNoImpersonate = 3073
RemoveAccount | RemoveUserAccount in Remove.dll. | msidbCustomActionTypeDll + msidbCustomActionTypeBinaryData + msidbCustomActionTypeInScript + msidbCustomActionTypeNoImpersonate = 3073
RollbackAccount | RemoveUserAccount in Remove.dll. | msidbCustomActionTypeDll + msidbCustomActionTypeBinaryData + msidbCustomActionTypeInScript + msidbCustomActionTypeRollback = 1281

Continue to Authoring the CustomAction Table.


Authoring the CustomAction Table

Enter records for the five sample custom actions created in the previous section to the CustomAction Table. For more information on how to populate the CustomAction table for this type of custom action see Custom Action Type 1.

CustomAction Table

Action | Type | Source | Target
ProcessAccounts | 1 | Process.dll | ProcessUserAccounts
UninstallAccounts | 1 | Process.dll | UninstallUserAccounts
CreateAccount | 3073 | Create.dll | CreateUserAccount
RemoveAccount | 3073 | Remove.dll | RemoveUserAccount
RollbackAccount | 1281 | Remove.dll | RemoveUserAccount

The C++ source code for the dynamic-link libraries are provided in the Windows Installer SDK. Use process.cpp to create the file Process.dll. Use create.cpp to create the file Create.dll. Use remove.cpp to create Remove.dll. Add these dynamic-link library files to the Binary table.

Binary Table

Name | Data
Process.dll | {binary data}
Create.dll | {binary data}
Remove.dll | {binary data}

Continue to Adding a Custom CustomUserAccounts Table.


Adding a Custom CustomUserAccounts Table

A specification of the sample is that user account information be read from a custom table in the installation database and not hard-coded into the custom action.

Add a custom table to the sample installation database named CustomUserAccounts to hold user account information. See Examples of Database Queries Using SQL and Script for an example of how to add a custom table. Use the following schema for the CustomUserAccounts table. See Column Definition Format for an explanation of the column types.

Column | Type | Key | Nullable | Description
UserName | s72 | Y | N | Name of user account being created.
TempPassWord | s25 |  | N | Temporary password for the user account. Note that the temporary password is visible and insecure.
Attributes | i4 |  | Y | Attributes for account. These are defined as the DWORD values for the usri1_flags member of the USER_INFO_1 structure.

After the CustomUserAccounts table has been added to the database you may edit this table using Orca, a table editor provided with the Windows Installer SDK, or another editor. Enter the following record in the CustomUserAccounts table to create a user account that does not require a password for TestUser. Note that the value of UR_PASSWD_NOTREQD is 32.

CustomUserAccounts Table

UserName | TempPassWord | Attributes
TestUser | 1 | 32

Add the following records to the _Validation table for the custom table.

_Validation Table

Table | Column | Nullable | MinValue | MaxValue | KeyTable | KeyColumn | Category | Set | Description
CustomUserAccounts | UserName | N |  |  |  |  | Text |  |
CustomUserAccounts | TempPassWord | N |  |  |  |  | Text |  |
CustomUserAccounts | Attributes | Y | 0 | 2147483647 |  |  | NULL |  |

Continue to Authoring the ActionText and Error Tables.


Authoring the ActionText and Error Tables

The sample specifications include sending ActionData messages when a custom action creates or removes a user account and reporting an error if an account cannot be created.

Enter the following entries into the ActionText table to provide information used by ActionText messages.

ActionText Table

Action | Description | Template
ProcessAccounts | Generating actions to create user accounts on the local computer. | Account: [1], Attributes: [2]
CreateAccount | Creating user account on the local computer. | Account: [1]
RemoveAccount | Removing user account from the local computer. | Account: [1]
RollbackAccount | Rolling back the creation of user accounts on the local computer. | Account: [1]
UninstallAccounts | Generating actions to remove user accounts on the local computer. | Account: [1]

Enter the following entries into the Error table to provide information used by error reporting.

Error Table

Error | Message
25001 | Unable to create user account '[2]' on the local machine. Error Code: [3].
25002 | User account '[2]' already exists on the local machine.
25003 | Unable to remove user account '[2]' on the local machine. Error Code: [3].
25004 | User account '[2]' does not exist on the local machine.

Continue to Authoring the InstallExecuteSequence Table.


Authoring the InstallExecuteSequence Table

The custom actions ProcessAccounts and UninstallAccounts generate the deferred custom actions that create, remove, or rollback user accounts. The custom actions ProcessAccounts and UninstallAccounts must be entered into the InstallExecuteSequence table to be executed. Add the following entries to the InstallExecuteSequence table. Because these custom actions must be a part of the script generation, both custom actions must be sequenced after the InstallInitialize action.

The condition on ProcessAccounts ensures the following. See Conditional Statement Syntax.

  • ProcessAccounts runs only on Windows NT or Windows 2000.
  • ProcessAccounts runs only if the component TestAccount is being installed locally on the computer.
  • The component Test Account is currently not installed or is installed to run from source.

The condition on UninstallAccount ensures the following.

  • UninstallAccounts runs only on Windows NT or Windows 2000.
  • UninstallAccounts runs only if the component TestAccount is installed locally on the computer.
  • The component Test Account is being removed or being installed to run from source.

InstallExecuteSequence Table

Action | Condition | Sequence
ProcessAccounts | VersionNT AND (?TestAccount=2 OR ?TestAccount=4) AND $TestAccount=3 | 1550
UninstallAccounts | VersionNT AND ?TestAccount=3 AND ($TestAccount=4 OR $TestAccount=2) | 1560

This completes the sample.


Custom Action Reference

The following sections reference information on custom actions.

  • Summary List of All Custom Action Types
  • Custom Action Return Processing Options
  • Custom Action Execution Scheduling Options
  • Custom Action In-Script Execution Options
  • Custom Action Return Values
  • Return Values of JScript and VBScript Custom Actions
  • Custom Action Type 1
  • Custom Action Type 17
  • Custom Action Type 2
  • Custom Action Type 18
  • Custom Action Type 50
  • Custom Action Type 34
  • Custom Action Type 51
  • Custom Action Type 35
  • Custom Action Type 5
  • Custom Action Type 21
  • Custom Action Type 53
  • Custom Action Type 37
  • Custom Action Type 6
  • Custom Action Type 22
  • Custom Action Type 54
  • Custom Action Type 38
  • Custom Action Type 7
  • Custom Action Type 23
  • Custom Action Type 39

See Also

About Custom Actions, Using Custom Actions


Summary List of All Custom Action Types

The following table lists the basic types of custom actions and shows the values that are in of the Type, Source, and Target fields of the CustomAction table for each type. The basic custom actions can be modified by including optional flag bits in the Type column. For descriptions of the options and the values see:

  • Custom Action Return Processing Options
  • Custom Action Execution Scheduling Options
  • Custom Action In-Script Execution Options

Use the links to the Basic Custom Action Type for a description and for the options available with the type.

Basic custom action type | Type | Source | Target
Custom Action Type 1 DLL file stored in a Binary table stream. | 1 | Key to Binary table | DLL entry point.
Custom Action Type 17 DLL file that is installed with a product. | 17 | Key to File table | DLL entry point.
Custom Action Type 2 EXE file stored in a Binary table stream. | 2 | Key to Binary table | Command line string.
Custom Action Type 18 EXE file that is installed with a product. | 18 | Key to File table | Command line string.
Custom Action Type 19 Displays a specified error message and returns failure, terminating the installation. | 19 | blank | Formatted text string. The literal message or an index into the Error table.
Custom Action Type 50 EXE file having a path specified by a property value. | 50 | Property name or key to Property table | Command line string.
Custom Action Type 34 EXE file having a path referencing a directory. | 34 | Key to Directory table. This is the working directory for execution. | The name of the executable file, an optional command line string, and an option a path to the EXE file. Quotes must be used around long file names.
Custom Action Type 5 JScript file stored in a Binary table stream. | 5 | Key to Binary table | An optional JScript function that can be called.
Custom Action Type 21 JScript file that is installed with a product. | 21 | Key to File table | An optional JScript function that can be called.
Custom Action Type 53 JScript text specified by a property value. | 53 | Property name or key to Property table | An optional JScript function that can be called.
Custom Action Type 37 JScript text stored in this sequence table. | 37 | NULL | A string of JScript code.
Custom Action Type 6 VBScript file stored in a Binary table stream. | 6 | Key to Binary table | An optional VBScript function that can be called.
Custom Action Type 22 VBScript file that is installed with a product. | 22 | Key to File table | An optional VBScript function that can be called.
Custom Action Type 54 VBScript text specified by a property value. | 54 | Property name or key to Property table. | An optional VBScript function that can be called.
Custom Action Type 38 VBScript text stored in this sequence table. | 38 | NULL | A string of VBScript code.
Custom Action Type 51 Property set with formatted text. | 51 | Property name or key to the Property table. This property is set by the formatted string in the Target field. | A formatted text string.
Custom Action Type 35 Directory set with formatted text. | 35 | A key to the Directory table. The designated directory is set by the formatted string in the Target field. | A formatted text string.
Custom Action Type 7 Installation of a package nested inside of the first package. See Nested Installation Actions. | 7 | Name of the sub-storage containing database of nested application. | Properties settings string.
Custom Action Type 23 Installation of a package that resides in the first application's source tree. See Nested Installation Actions. | 23 | Path of nested package specified relative to the root of the source location. | Properties settings string.
Custom Action Type 39 Installation of an application that is advertised or already installed. See Nested Installation Actions. | 39 | Product code for the application. | Properties settings string.


Custom Action Type 1

This custom action calls a dynamic link library (DLL) written in C or C++.

Source

The DLL is generated from a temporary binary stream. The Source field of the CustomAction table contains a key to the Binary table.

The Data column in the Binary table contains the stream data. A separate stream is allocated for each row. New binary data can be inserted from a file by using MsiRecordSetStream followed by MsiViewModify to insert the record into the table. When the custom action is invoked, the stream data is copied to a temporary file, which is then processed depending upon the type of custom action.

Type Value

Include the following flag bits in the Type column of the CustomAction table to specify the basic numeric type.

Constants | Hexadecimal | Decimal
msidbCustomActionTypeDll + msidbCustomActionTypeBinaryData | 0x001 | 1

Target

The DLL is called through the entry point named in the Target field of the CustomAction table, passing a single argument that is the handle to the current install session. The entry point name specified in the table must match that exported from the DLL. Note that if the entry function is not specified by a .DEF file or by a /EXPORT: linker specification, the name may have a leading underscore and a "@4" suffix. The called function must specify the __stdcall calling convention.

Return Processing Options

Include optional flag bits in the Type column of the CustomAction table to specify return processing options. For a description of the options and the values, see Custom Action Return Processing Options.

Execution Scheduling Options

Include optional flag bits in the Type column of the CustomAction table to specify execution scheduling options. These options control the multiple execution of custom actions. For a description of the options, see Custom Action Execution Scheduling Options.

In-Script Execution Options

Include optional flag bits in the Type column of the CustomAction table to specify an in-script execution option. These options copy the action code into the execution, rollback, or commit script. For a description of the options, see Custom Action In-Script Execution Options.

Return Values

See Custom Action Return Values.

Remarks

A custom action that calls a dynamic-link library (DLL) requires a handle to the installation session. If this is also a deferred execution custom action, the session may no longer exist during execution of the installation script. For information on how a custom action of this type can obtain context information, see Obtaining Context Information for Deferred Execution Custom Actions.

When a database table is exported, each stream is written as a separate file in the subfolder named after the table, using the primary key as the file name (Name column for the Binary table), with a default extension of ".ibd". The name should use 8.3 format if the file system or version control system does not support long file names. The persistent archive file replaces the stream data with the file name used, so that the data can be located when the table is imported.

See Also

Dynamic-Link Libraries, Custom Action Reference List, Obtaining Context Information for Deferred Execution Custom Actions


Custom Action Type 17

This custom action calls a dynamic link library (DLL) written in C or C++.

Source

The DLL is installed with the application during the current session. The Source field of the CustomAction table contains a key to the File table. The location of the custom action code is determined by the resolution of the target path for this file; therefore this custom action must be called after that file has been installed and before it is removed.

Type Value

Include the following value in the Type column of the CustomAction table to specify the basic numeric type.

Constants | Hexadecimal | Decimal
msidbCustomActionTypeDll + msidbCustomActionTypeSourceFile | 0x011 | 17

Target

The DLL is called through the entry point named in the Target field of the CustomAction table, passing a single argument that is the handle to the current install session. The entry point name specified in the table must match that exported from the DLL. Note that if the entry function is not specified by a .DEF file or by a /EXPORT: linker specification, the name may have a leading underscore and a "@4" suffix. The called function must specify the __stdcall calling convention.

Return Processing Options

Include optional flag bits in the Type column of the CustomAction table to specify return processing options. For a description of the options and the values, see Custom Action Return Processing Options.

Execution Scheduling Options

Include optional flag bits in the Type column of the CustomAction table to specify execution scheduling options. These options control the multiple execution of custom actions. For a description of the options, see Custom Action Execution Scheduling Options.

In-Script Execution Options

Include optional flag bits in the Type column of the CustomAction table to specify an in-script execution option. These options copy the action code into the execution, rollback, or commit script. For a description of the options, see Custom Action In-Script Execution Options.

Return Values

See Custom Action Return Values.

Remarks

A custom action that calls a dynamic-link library (DLL) requires a handle to the installation session. If this is also a deferred execution custom action, the session may no longer exist during execution of the installation script. For information on how a custom action of this type can obtain context information, see Obtaining Context Information for Deferred Execution Custom Actions.

Custom actions execute in a separate thread, and may have limited access to the system. Custom actions that run asynchronously block the main thread at the termination of either the current sequence or the install session until they return.

Custom actions that reference an installed file as their source, such as Custom Action Type 17 (DLL), must adhere to the following sequencing restrictions.

  • The custom action must be sequenced after the CostFinalize action. This is so that the custom action can resolve the path needed to locate the DLL.
  • If the source file is not already installed on the computer, deferred (in-script) custom actions of this type must be sequenced after the InstallFiles action.
  • If the source file is not already installed on the computer, non-deferred custom actions of this type must be sequenced after the InstallFinalize action.

See Also

Deferred Execution Custom Actions; Dynamic-Link Libraries, Custom Action Reference List, Sequencing Custom Actions.


Custom Action Type 2

This custom action calls an executable launched with a command line.

Source

The executable is generated from a temporary binary stream. The Source field of the CustomAction table contains a key to the Binary table. The Data column in the Binary table contains the stream data. A separate stream is allocated for each row.

New binary data can be inserted from a file by using MsiRecordSetStream followed by MsiViewModify to insert the record into the table. When the custom action is invoked, the stream data is copied to a temporary file, which is then processed depending upon the type of custom action.

Type Value

Include the following value in the Type column of the CustomAction table to specify the basic numeric type.

Constants | Hexadecimal | Decimal
msidbCustomActionTypeExe + msidbCustomActionTypeBinaryData | 0x002 | 2

Target

The Target column of the CustomAction table contains the command line string for the executable named in the Source column.

Return Processing Options

Include optional flag bits in the Type column of the CustomAction table to specify return processing options. For a description of the options and the values, see Custom Action Return Processing Options.

Execution Scheduling Options

Include optional flag bits in the Type column of the CustomAction table to specify execution scheduling options. These options control the multiple execution of custom actions. For a description of the options, see Custom Action Execution Scheduling Options.

In-Script Execution Options

Include optional flag bits in the Type column of the CustomAction table to specify an in-script execution option. These options copy the action code into the execution, rollback, or commit script. For a description of the options, see Custom Action In-Script Execution Options.

Return Values

Custom actions that are executable files must return a value of 0 for success. The installer interprets any other return value as failure. To ignore return values set the msidbCustomActionTypeContinue bit flag in the Type field of the CustomAction table.

Remarks

A custom action that launches an executable takes a command line, which commonly contains properties that are designated dynamically. If this is also a deferred execution custom action, the installer uses CreateProcessAsUser or CreateProcess to create the process when the custom action is invoked from the installation script.

When a database table is exported, each stream is written as a separate file in the subfolder named after the table, using the primary key as the file name (Name column for the Binary table), with a default extension of ".ibd". The name should use 8.3 format if the file system or version control system does not support long file names. The persistent archive file replaces the stream data with the file name used, so that the data can be located when the table is imported.

See Also

Executable Files, Custom Action Reference List, CustomAction table


Custom Action Type 18

This custom action calls an executable launched with a command line.

Source

The executable is generated from a file installed with the application. The Source field of the CustomAction table contains a key to the File table. The location of the custom action code is determined by the resolution of the target path for this file; therefore this custom action must be called after the file has been installed and before it is removed.

Type Value

Include the following value in the Type column of the CustomAction table to specify the basic numeric type.

Constants | Hexadecimal | Decimal
msidbCustomActionTypeExe + msidbCustomActionTypeSourceFile | 0x012 | 18

Target

The Target column of the CustomAction table contains the command line string for the executable identified in the Source column.

Return Processing Options

Include optional flag bits in the Type column of the CustomAction table to specify return processing options. For a description of the options and the values, see Custom Action Return Processing Options.

Execution Scheduling Options

Include optional flag bits in the Type column of the CustomAction table to specify execution scheduling options. These options control the multiple execution of custom actions. For a description of the options, see Custom Action Execution Scheduling Options.

In-Script Execution Options

Include optional flag bits in the Type column of the CustomAction table to specify an in-script execution option. These options copy the action code into the execution, rollback, or commit script. For a description of the options, see Custom Action In-Script Execution Options.

Return Values

Custom actions that are executable files must return a value of 0 for success. The installer interprets any other return value as failure. To ignore return values set the msidbCustomActionTypeContinue bit flag in the Type field of the CustomAction table.

Remarks

A custom action that launches an executable takes a command line, which commonly contains properties that are designated dynamically. If this is also a deferred execution custom action, the installer uses CreateProcessAsUser or CreateProcess to create the process when the custom action is invoked from the installation script.

Custom actions that reference an installed file as their source, such as Custom Action Type 18 (EXE), must adhere to the following sequencing restrictions.

  • The custom action must be sequenced after the CostFinalize action. This is so that the custom action can resolve the path needed to locate the EXE.
  • If the source file is not already installed on the computer, deferred (in-script) custom actions of this type must be sequenced after the InstallFiles action.
  • If the source file is not already installed on the computer, non-deferred custom actions of this type must be sequenced after the InstallFinalize action.

See Also

Executable Files, Custom Action Reference List, Sequencing Custom Actions


Custom Action Type 19

This custom action displays a specified error message, returns failure, and then terminates the installation. The error message displayed can be supplied as a string or as an index into the Error table.

Source

Leave the Source column of the CustomAction table blank.

Type Value

Include the following value in the Type column of the CustomAction table to specify the basic numeric type.

Constants | Hexadecimal | Decimal
msidbCustomActionTypeTextData + msidbCustomActionTypeSourceFile | 0x013 | 19

Target

The Target column of the CustomAction table contains a text string formatted using the functionality specified in MsiFormatRecord (without the numeric field specifiers). Parameters to be replaced are enclosed in square brackets, […], and may be properties, environment variables (% prefix), file paths (# prefix), or component directory paths ($ prefix). If after formatting the string evaluates to an integer, that integer is used as an index into the Error table to retrieve the message to display. If after formatting the string contains non-numeric characters, the string itself is displayed as the message

Return Processing Options

Not used.

Execution Scheduling Options

Not used.

In-Script Execution Options

Not used.

Return Values

See Custom Action Return Values.

Remarks

For example the custom actions CAError1, CAError2, CAError3, and CAError4 return messages.

CustomAction Table

Action | Type | Source | Target
CAError1 | 19 |  | [Prop1]
CAError2 | 19 |  | Installation failure due to Error2.
CAError3 | 19 |  | 25000
CAError4 | 19 |  | [Prop2]

Property Table

Property | Value
Prop1 | "Installation failure due to Error1."
Prop2 | "25100"

Error Table

Code | Message
25000 | Installation failure due to Error3
25100 | Installation failure due to Error4.

These custom actions return the following error messages:

Custom action | Returned message string
CAError1 | Installation failure due to Error1.
CAError2 | Installation failure due to Error2.
CAError3 | Installation failure due to Error3
CAError4 | Installation failure due to Error4.

See Also

Custom Action Return Values, Custom Action Reference List


Custom Action Type 50

This custom action calls an executable launched with a command line.

See also Executable Files.

Source

The executable is generated from an existing file. The Source field of the CustomAction table contains a key to the Property table for a property containing the full path to the executable file.

Type Value

Include the following value in the Type column of the CustomAction table to specify the basic numeric type.

Constants | Hexadecimal | Decimal
msidbCustomActionTypeExe + msidbCustomActionTypeProperty | 0x032 | 50

Target

The Target column of the CustomAction table contains the command line string for the executable identified in the Source column.

Return Processing Options

Include optional flag bits in the Type column of the CustomAction table to specify return processing options. For a description of the options and the values, see Custom Action Return Processing Options.

Execution Scheduling Options

Include optional flag bits in the Type column of the CustomAction table to specify execution scheduling options. These options control the multiple execution of custom actions. For a description of the options, see Custom Action Execution Scheduling Options.

In-Script Execution Options

Include optional flag bits in the Type column of the CustomAction table to specify an in-script execution option. These options copy the action code into the execution, rollback, or commit script. For a description of the options, see Custom Action In-Script Execution Options.

Return Values

Custom actions that are executable files must return a value of 0 for success. The installer interprets any other return value as failure. To ignore return values set the msidbCustomActionTypeContinue bit flag in the Type field of the CustomAction table.

Remarks

A custom action that launches an executable takes a command line, which commonly contains properties that are designated dynamically. If this is also a deferred execution custom action, the installer uses CreateProcessAsUser or CreateProcess to create the process when the custom action is invoked from the installation script.

See Also

Custom Action Reference, About Custom Actions, Using Custom Actions,


Custom Action Type 34

This custom action calls an executable launched with a command line. For more information, see Executable Files.

Source

The executable is generated from an existing file. The Source field of the CustomAction table contains a foreign key to the Directory table referencing a separate working directory for the executable. This is used to resolve the full path to the directory, which is then appended to the command line in the Target field.

Type Value

Include the following value in the Type column of the CustomAction table to specify the basic numeric type.

Constants | Hexadecimal | Decimal
msidbCustomActionTypeExe + msidbCustomActionTypeDirectory | 0x022 | 34

Target

The Target column of the CustomAction table contains the command line string for the executable and the complete path to the executable, using quotation marks and property parameters as necessary. The command line in this field must begin with the executable's file name.

Return Processing Options

Include optional flag bits in the Type column of the CustomAction table to specify return processing options. For a description of the options and the values, see Custom Action Return Processing Options.

Execution Scheduling Options

Include optional flag bits in the Type column of the CustomAction table to specify execution scheduling options. These options control the multiple execution of custom actions. For a description of the options, see Custom Action Execution Scheduling Options.

In-Script Execution Options

Include optional flag bits in the Type column of the CustomAction table to specify an in-script execution option. These options copy the action code into the execution, rollback, or commit script. For a description of the options, see Custom Action In-Script Execution Options.

Return Values

Custom actions that are executable files must return a value of 0 for success. The installer interprets any other return value as failure. To ignore return values set the msidbCustomActionTypeContinue bit flag in the Type field of the CustomAction table.

Remarks

A custom action that launches an executable takes a command line, which commonly contains properties that are designated dynamically. If this is also a deferred execution custom action, the installer uses CreateProcessAsUser or CreateProcess to create the process when the custom action is invoked from the installation script.

See Also

Custom Action Reference, About Custom Actions, Using Custom Actions,


Custom Action Type 51

This custom action sets a property from a formatted text string.

To affect a property used in a condition on a component or feature, the custom action must come before the CostFinalize action in the action sequence.

Source

The Source field of the CustomAction table can contain either the name of a property or a key to the Property table. This property is set by the formatted string in the Target field using MsiSetProperty.

Type Value

Include the following value in the Type column of the CustomAction table to specify the basic numeric type.

Constants | Hexadecimal | Decimal
msidbCustomActionTypeTextData + msidbCustomActionTypeProperty | 0x033 | 51

Target

The Target column of the CustomAction table contains a text string formatted using the functionality specified in MsiFormatRecord (without the numeric field specifiers). Parameters to be replaced are enclosed in square brackets, […], and may be properties, environment variables (% prefix), file paths (# prefix), or component directory paths ($ prefix).

Return Processing Options

Not used.

Execution Scheduling Options

Include optional flag bits in the Type column of the CustomAction table to specify execution scheduling options. These options control the multiple execution of custom actions. For a description of the options, see Custom Action Execution Scheduling Options.

In-Script Execution Options

Not used.

Return Values

See Custom Action Return Values.

See Also

Custom Action Reference, About Custom Actions, Formatted Text Custom Actions, Using Custom Actions, Custom Action Return Values


Custom Action Type 35

This custom action sets the install directory from a formatted text string.

Source

The Source field of the CustomAction table contains a key to the Directory table. The designated directory is set by the formatted string in the Target field using MsiSetTargetPath. This sets the target path and associated property to the expanded value of the formatted text string in the Target field.

Type Value

Include the following value in the Type column of the CustomAction table to specify the basic numeric type.

Constants | Hexadecimal | Decimal
msidbCustomActionTypeTextData + msidbCustomActionTypeDirectory | 0x023 | 35

Target

The Target column of the CustomAction table contains a text string formatted using the functionality specified in MsiFormatRecord (without the numeric field specifiers). Parameters to be replaced are enclosed in square brackets, […], and may be properties, environment variables (% prefix), file paths (# prefix), or component directory paths ($ prefix). Note that directory paths always end with a directory separator.

Return Processing Options

Not used.

Execution Scheduling Options

Include optional flag bits in the Type column of the CustomAction table to specify execution scheduling options. These options control the multiple execution of custom actions. For a description of the options, see Custom Action Execution Scheduling Options.

In-Script Execution Options

Not used.

Return Values

See Custom Action Return Values.

See Also

Custom Action Reference, About Custom Actions, Formatted Text Custom Actions, Using Custom Actions, Custom Action Return Values


Custom Action Type 5

This custom action is written in Jscript, such as JavaScript or ECMA 262. Windows Installer does not support JScript 1.0. For more information, see Scripts.

Source

The script is generated from a temporary binary stream. The Source field of the CustomAction table contains a key to the Binary table. The Data column in the Binary table contains the stream data. A separate stream is allocated for each row.

New binary data can be inserted from a file by using MsiRecordSetStream followed by MsiViewModify to insert the record into the table. When the custom action is invoked, the stream data is copied to a temporary file, which is then processed according to the type of custom action.

Type Value

Include the following value in the Type column of the CustomAction table to specify the basic numeric type.

Constants | Hexadecimal | Decimal
msidbCustomActionTypeJScript + msidbCustomActionTypeBinaryData | 0x05 | 5

Target

The Target field of the CustomAction table contains an optional script function. Processing first sends the script for parsing and then calls the optional script function.

Return Processing Options

Include optional flag bits in the Type column of the CustomAction table to specify return processing options. For a description of the options and the values, see Custom Action Return Processing Options.

Execution Scheduling Options

Include optional flag bits in the Type column of the CustomAction table to specify execution scheduling options. These options control the multiple execution of custom actions. For a description of the options, see Custom Action Execution Scheduling Options.

In-Script Execution Options

Include optional flag bits in the Type column of the CustomAction table to specify an in-script execution option. These options copy the action code into the execution, rollback, or commit script. For a description of the options, see Custom Action In-Script Execution Options.

Return Values

Optional functions written in script must return one of the values described in Return Values of JScript and VBScript Custom Actions.

Remarks

A custom action that is written in JScript or VBScript requires the install Session object. The installer attaches the Session Object to the script with the name "Session". Because the Session object may not exist during an installation rollback, a deferred custom action written in script must use one of the methods or properties of the Session object described in the section Obtaining Context Information for Deferred Execution Custom Actions to retrieve its context.

When a database table is exported, each stream is written as a separate file in the subfolder named after the table, using the primary key as the file name (Name column for the Binary table), with a default extension of ".ibd". The name should use 8.3 format if the file system or version control system does not support long file names. The persistent archive file replaces the stream data with the file name used, so that the data can be located when the table is imported.

See Also

Custom Action Reference, About Custom Actions, Using Custom Actions, Custom Action Return Values


Custom Action Type 21

This custom action is written in JScript, such as JavaScript or ECMA 262. Windows Installer does not support JScript 1.0. For more information, see Scripts.

Source

The script is installed with the application during the current session. The Source field of the CustomAction table contains a key to the File table. The location of the custom action code is determined by the resolution of the target path for this file; therefore this custom action must be called after the file has been installed and before it is removed.

Type Value

Include the following value in the Type column of the CustomAction table to specify the basic numeric type.

Constants | Hexadecimal | Decimal
msidbCustomActionTypeJScript + msidbCustomActionTypeSourceFile | 0x015 | 21

Target

The Target field of the CustomAction table contains an optional script function. Processing first sends the script for parsing and then calls the optional script function.

Return Processing Options

Include optional flag bits in the Type column of the CustomAction table to specify return processing options. For a description of the options and the values, see Custom Action Return Processing Options.

Execution Scheduling Options

Include optional flag bits in the Type column of the CustomAction table to specify execution scheduling options. These options control the multiple execution of custom actions. For a description of the options, see Custom Action Execution Scheduling Options.

In-Script Execution Options

Include optional flag bits in the Type column of the CustomAction table to specify an in-script execution option. These options copy the action code into the execution, rollback, or commit script. For a description of the options, see Custom Action In-Script Execution Options.

Return Values

Optional functions written in script must return one of the values described in Return Values of JScript and VBScript Custom Actions.

Remarks

A custom action that is written in JScript or VBScript requires the install Session object. The installer attaches the Session Object to the script with the name "Session". Because the Session object may not exist during an installation rollback, a deferred custom action written in script must use one of the methods or properties of the Session object described in the section Obtaining Context Information for Deferred Execution Custom Actions to retrieve its context.

Custom actions that reference an installed file as their source, such as Custom Action Type 21 (JScript), must adhere to the following sequencing restrictions.

  • The custom action must be sequenced after the CostFinalize action. This is so that the custom action can resolve the path needed to locate the source file containing the JScript.
  • If the source file is not already installed on the computer, deferred (in-script) custom actions of this type must be sequenced after the InstallFiles action.
  • If the source file is not already installed on the computer, non-deferred custom actions of this type must be sequenced after the InstallFinalize action.

See Also

Custom Action Reference, About Custom Actions, Using Custom Actions, Custom Action Return Values, Sequencing Custom Actions


Custom Action Type 53

This custom action is written in JScript, such as JavaScript or ECMA 262. Windows Installer does not support JScript 1.0. For more information, see Scripts.

Source

The Source field of the CustomAction table contains a property name or a key to the Property table for a property containing the script text.

Type Value

Include the following value in the Type column of the CustomAction table to specify the basic numeric type.

Constants | Hexadecimal | Decimal
msidbCustomActionTypeJScript + msidbCustomActionTypeProperty | 0x035 | 53

Target

The Target field of the CustomAction table contains an optional script function. Processing first sends the script for parsing and then calls the optional script function.

Return Processing Options

Include optional flag bits in the Type column of the CustomAction table to specify return processing options. For a description of the options and the values, see Custom Action Return Processing Options.

Execution Scheduling Options

Include optional flag bits in the Type column of the CustomAction table to specify execution scheduling options. These options control the multiple execution of custom actions. For a description of the options, see Custom Action Execution Scheduling Options.

In-Script Execution Options

Include optional flag bits in the Type column of the CustomAction table to specify an in-script execution option. These options copy the action code into the execution, rollback, or commit script. For a description of the options, see Custom Action In-Script Execution Options.

Return Values

Optional functions written in script must return one of the values described in Return Values of JScript and VBScript Custom Actions.

Remarks

A custom action that is written in JScript requires the install Session object. Because the Session object may not exist during an installation rollback, a deferred custom action written in script uses one of the methods described in Obtaining Context Information for Deferred Execution Custom Actions.

See Also

Custom Action Reference, About Custom Actions, Using Custom Actions, Custom Action Return Values


Custom Action Type 37

This custom action is written in JScript, such as JavaScript or ECMA 262. Windows Installer does not support JScript 1.0. For more information, see Scripts.

Source

The Source field of the CustomAction table contains the null value. The script code for the custom action is stored as a string of literal script text in the Target field.

Type Value

Include the following value in the Type column of the CustomAction table to specify the basic numeric type.

Constants | Hexadecimal | Decimal
msidbCustomActionTypeJScript + msidbCustomActionTypeDirectory | 0x025 | 37

Target

The Target field of the CustomAction table contains the script code for the custom action as a string of literal script text.

Return Processing Options

Include optional flag bits in the Type column of the CustomAction table to specify return processing options. For a description of the options and the values, see Custom Action Return Processing Options.

Execution Scheduling Options

Include optional flag bits in the Type column of the CustomAction table to specify execution scheduling options. These options control the multiple execution of custom actions. For a description of the options, see Custom Action Execution Scheduling Options.

In-Script Execution Options

Include optional flag bits in the Type column of the CustomAction table to specify an in-script execution option. These options copy the action code into the execution, rollback, or commit script. For a description of the options, see Custom Action In-Script Execution Options.

Return Values

This custom action type always returns success.

Remarks

A custom action that is written in JScript or VBScript requires the install Session object. The installer attaches the Session Object to the script with the name "Session". Because the Session object may not exist during an installation rollback, a deferred custom action written in script must use one of the methods or properties of the Session object described in the section Obtaining Context Information for Deferred Execution Custom Actions to retrieve its context.

See Also

Custom Action Reference, About Custom Actions, Using Custom Actions, Custom Action Return Values


Custom Action Type 6

This custom action is written in VBScript. For more information, see Scripts.

Source

The script is generated from a temporary binary stream. The Source field of the CustomAction table contains a key to the Binary table. The Data column in the Binary table contains the stream data. A separate stream is allocated for each row.

New binary data can be inserted from a file by using MsiRecordSetStream followed by MsiViewModify to insert the record into the table. When the custom action is invoked, the stream data is copied to a temporary file, which is then processed depending upon the type of custom action.

Type Value

Include the following value in the Type column of the CustomAction table to specify the basic numeric type.

Constants | Hexadecimal | Decimal
msidbCustomActionTypeVBScript + msidbCustomActionTypeBinaryData | 0x006 | 6

Target

The Target field of the CustomAction table contains an optional script function. Processing first sends the script for parsing and then calls the optional script function.

Return Processing Options

Include optional flag bits in the Type column of the CustomAction table to specify return processing options. For a description of the options and the values, see Custom Action Return Processing Options.

Execution Scheduling Options

Include optional flag bits in the Type column of the CustomAction table to specify execution scheduling options. These options control the multiple execution of custom actions. For a description of the options, see Custom Action Execution Scheduling Options.

In-Script Execution Options

Include optional flag bits in the Type column of the CustomAction table to specify an in-script execution option. These options copy the action code into the execution, rollback, or commit script. For a description of the options, see Custom Action In-Script Execution Options.

Return Values

Optional functions written in script must return one of the values described in Return Values of JScript and VBScript Custom Actions.

Remarks

A custom action that is written in JScript or VBScript requires the install Session object. The installer attaches the Session Object to the script with the name "Session". Because the Session object may not exist during an installation rollback, a deferred custom action written in script must use one of the methods or properties of the Session object described in the section Obtaining Context Information for Deferred Execution Custom Actions to retrieve its context.

When a database table is exported, each stream is written as a separate file in the subfolder named after the table, using the primary key as the file name (Name column for the Binary table), with a default extension of ".ibd". The name should use 8.3 format if the file system or version control system does not support long file names. The persistent archive file replaces the stream data with the file name used, so that the data can be located when the table is imported.

See Also

Custom Action Reference, About Custom Actions, Using Custom Actions, Custom Action Return Values


Custom Action Type 22

This custom action is written in VBScript.

See also Scripts.

Source

The script is installed with the application during the current session. The Source field of the CustomAction table contains a key to the File table. The location of the custom action code is determined by the resolution of the target path for this file; therefore this custom action must be called after the file has been installed and before it is removed.

Type Value

Include the following value in the Type column of the CustomAction table to specify the basic numeric type.

Constants | Hexadecimal | Decimal
msidbCustomActionTypeVBScript + msidbCustomActionTypeSourceFile | 0x016 | 22

Target

The Target field of the CustomAction table contains an optional script function. Processing first sends the script for parsing and then calls the optional script function.

Return Processing Options

Include optional flag bits in the Type column of the CustomAction table to specify return processing options. For a description of the options and the values, see Custom Action Return Processing Options.

Execution Scheduling Options

Include optional flag bits in the Type column of the CustomAction table to specify execution scheduling options. These options control the multiple execution of custom actions. For a description of the options, see Custom Action Execution Scheduling Options.

In-Script Execution Options

Include optional flag bits in the Type column of the CustomAction table to specify an in-script execution option. These options copy the action code into the execution, rollback, or commit script. For a description of the options, see Custom Action In-Script Execution Options.

Return Values

Optional functions written in script must return one of the values described in Return Values of JScript and VBScript Custom Actions.

Remarks

A custom action that is written in JScript or VBScript requires the install Session object. This is of the type Session Object and the installer attaches it to the script with the name "Session". Because the Session object may not exist during an installation rollback, a deferred custom action written in script must use one of the methods or properties of the Session object described in the section Obtaining Context Information for Deferred Execution Custom Actions to retrieve its context.

Custom actions that reference an installed file as their source, such as Custom Action Type 22 (VBcript), must adhere to the following sequencing restrictions.

  • The custom action must be sequenced after the CostFinalize action. This is so that the custom action can resolve the path needed to locate the source file containing the VBScript.
  • If the source file is not already installed on the computer, deferred (in-script) custom actions of this type must be sequenced after the InstallFiles action.
  • If the source file is not already installed on the computer, non-deferred custom actions of this type must be sequenced after the InstallFinalize action.

See Also

Custom Action Reference, About Custom Actions, Using Custom Actions, Custom Action Return Values, Sequencing Custom Actions


Custom Action Type 54

This custom action is written in VBScript.

See also Scripts.

Source

The Source field of the CustomAction table contains a property name or a key to the Property table for a property containing the script text.

Type Value

Include the following value in the Type column of the CustomAction table to specify the basic numeric type.

Constants | Hexadecimal | Decimal
msidbCustomActionTypeVBScript + msidbCustomActionTypeProperty | 0x036 | 54

Target

The Target field of the CustomAction table contains an optional script function. Processing first sends the script for parsing and then calls the optional script function.

Return Processing Options

Include optional flag bits in the Type column of the CustomAction table to specify return processing options. For a description of the options and the values, see Custom Action Return Processing Options.

Execution Scheduling Options

Include optional flag bits in the Type column of the CustomAction table to specify execution scheduling options. These options control the multiple execution of custom actions. For a description of the options, see Custom Action Execution Scheduling Options.

In-Script Execution Options

Include optional flag bits in the Type column of the CustomAction table to specify an in-script execution option. These options copy the action code into the execution, rollback, or commit script. For a description of the options, see Custom Action In-Script Execution Options.

Return Values

Optional functions written in script must return one of the values described in Return Values of JScript and VBScript Custom Actions.

Remarks

A custom action that is written in JScript or VBScript requires the install Session object. The installer attaches the Session Object to the script with the name "Session". Because the Session object may not exist during an installation rollback, a deferred custom action written in script must use one of the methods or properties of the Session object described in the section Obtaining Context Information for Deferred Execution Custom Actions to retrieve its context.

See Also

Custom Action Reference, About Custom Actions, Using Custom Actions, Custom Action Return Values


Custom Action Type 38

This custom action is written in VBScript.

See also Scripts.

Source

The Source field of the CustomAction table contains the null value. The script code for the custom action is stored as a string of literal script text in the Target field.

Type Value

Include the following value in the Type column of the CustomAction table to specify the basic numeric type.

Constants | Hexadecimal | Decimal
msidbCustomActionTypeVBScript + msidbCustomActionTypeDirectory | 0x026 | 38

Target

The Target field of the CustomAction table contains the script code for the custom action as a string of literal script text.

Return Processing Options

Include optional flag bits in the Type column of the CustomAction table to specify return processing options. For a description of the options and the values, see Custom Action Return Processing Options.

Execution Scheduling Options

Include optional flag bits in the Type column of the CustomAction table to specify execution scheduling options. These options control the multiple execution of custom actions. For a description of the options, see Custom Action Execution Scheduling Options.

In-Script Execution Options

Include optional flag bits in the Type column of the CustomAction table to specify an in-script execution option. These options copy the action code into the execution, rollback, or commit script. For a description of the options, see Custom Action In-Script Execution Options.

Return Values

This custom action type always returns success.

Remarks

A custom action that is written in JScript or VBScript requires the install Session object. The installer attaches the Session Object to the script with the name "Session". Because the Session object may not exist during an installation rollback, a deferred custom action written in script must use one of the methods or properties of the Session object described in the section Obtaining Context Information for Deferred Execution Custom Actions to retrieve its context.

See Also

Custom Action Reference, About Custom Actions, Using Custom Actions, Custom Action Return Values


Custom Action Type 7

This custom action installs another installer package that is nested inside of the first package. See Nested Installation Actions.

Source

The database of the nested application is stored as a sub-storage of the package, and the name of the sub-storage is designated in the Source field of the CustomAction table.

Numeric Type

Type name | Value
msidbCustomActionTypeInstall + msidbCustomActionTypeBinaryData | 7

Target

The Target field of the CustomAction table contains properties settings to be passed to the nested installation. These property settings can specify features.

Return Processing Options

The nested install session runs as a separate thread in the current process. A nested install cannot run asynchronously.

See Custom Action Return Processing Options.

Execution Scheduling Options

Options flags are available to control the potential multiple execution of custom actions. See Custom Action Execution Scheduling Options.

In-Script Execution Options

Not used.

Return Values

The return status from the nested install is treated the same as any other action, thus user exit, failure, suspend, and success is processed accordingly.

Remarks

A conditional expression is required to enable the nested install at either install or removal of the associated component or feature.

See Also

Custom Action Reference, About Custom Actions, Using Custom Actions, Custom Action Return Values


Custom Action Type 23

This custom action installs another installer package that resides in the application's source tree.

See also Nested Installation Actions.

Source

The location of the nested installation package is specified relative to the root of the source location by the Source field of the CustomAction table.

Numeric Type

Type name | Value
msidbCustomActionTypeInstall + msidbCustomActionTypeSourceFile | 23

Target

The Target field of the CustomAction table contains properties settings that are to be passed to the nested installation. These property settings can specify features.

Return Processing Options

The nested install session runs as a separate thread in the current process. A nested install cannot run asynchronously.

See Custom Action Return Processing Options.

Execution Scheduling Options

Options flags are available to control the potential multiple execution of custom actions. See Custom Action Execution Scheduling Options.

In-Script Execution Options

Not used.

Return Values

The return status from the nested install is treated the same as any other action, thus user exit, failure, suspend, and success is processed accordingly.

Remarks

A conditional expression is required to enable the nested install at either install or removal of the associated component or feature.

See Also

Custom Action Reference, About Custom Actions, Using Custom Actions, Custom Action Return Values


Custom Action Type 39

Type 39 custom action installs an application that is advertised or already installed. This custom action type may used to reinstall or remove a product that has been installed as a nested installation by the current product's installation package. The Type 39 custom action cannot be used to reinstall, or remove any product that previously was installed by any other means. For example, if the secondary product is installed using a Type 39, Type 23, or Type 7 custom action during the installation of the primary product, a Type 39 custom action may be used to remove the secondary product when the primary product is uninstalled.

See also Nested Installation Actions.

Source

The Source field of the CustomAction table contains the product code for the application.

Numeric Type

Type name | Value
msidbCustomActionTypeInstall + msidbCustomActionTypeDirectory | 39

Target

The Target field of the CustomAction table contains properties settings that are to be passed to the nested installation. These property settings can specify features.

Return Processing Options

The custom action type 39 fails if the application is not advertised or installed. To avoid this failure, you must set the msidbCustomActionTypeContinue flag.

A nested install cannot run asynchronously.

See Custom Action Return Processing Options.

Execution Scheduling Options

Options flags are available to control the potential multiple execution of custom actions. See Custom Action Execution Scheduling Options.

In-Script Execution Options

Not used.

Return Values

The return values from a nested installation are the same as other custom actions. See Custom Action Return Values.

Remarks

A conditional expression is required to enable the nested install at either install or removable of the associated component or feature.

See Also

Custom Action Reference, About Custom Actions, Using Custom Actions


Custom Action Return Processing Options

The following option flags can be used to control the processing of the custom action thread. They are used to specify that the main and custom action threads run synchronously (the installer waits for the custom action thread to complete before resuming the main installation thread) or asynchronously (the installer runs the custom action simultaneously as the main installation continues).

To enable these options add the value indicated in this table to the value in the Type field of the CustomAction table.

Constant | Hexadecimal | Decimal | Description
(none) | 0x00000000 | +0 | Synchronous execution. Fails if exit code not 0. If the flag msidbCustomActionTypeContinue is not set then the custom action must return one of the return values described in Custom Action Return Values.
msidbCustomActionTypeContinue | 0x00000040 | +64 | Synchronous execution. Ignores exit code and continues.
msidbCustomActionTypeAsync | 0x00000080 | +128 | Asynchronous execution. Waits for exit code at sequence end. This option cannot be used with Nested Installation Actions or Rollback Custom Actions.
msidbCustomActionTypeAsync + msidbCustomActionTypeContinue | 0x00000040 + 0x00000080 | +192 | Asynchronous execution. No wait for completion. Execution continues after installer terminates. This option cannot be used with Nested Installation Actions.


Custom Action Execution Scheduling Options

Because a custom action can be scheduled in both the UI and execute sequence tables, and can be executed either in the service or client process, a custom action can potentially execute multiple times.

Note that the installer:

  • Executes actions in a sequence table immediately by default.
  • Does not execute an action if the conditional expression field of the sequence table evaluates to False.
  • Processes the UI sequence table in the client process if the internal user's interface level is set to the full UI mode (see MsiSetInternalUI for a description of UI levels).
  • Is a service registered by default when using Windows NT/Windows 2000 and, in this case, the execute sequence table is processed in the installer service.
  • Processes the execution sequence table in the client process by default when using Windows 95 or Windows 98.

You can use the following option flags to control multiple immediate execution of custom actions. To set an option add the value in this table to the value in the Type field of the CustomAction table. None of the flags in the following table should be used with deferred execution custom actions.

Constant | Hexadecimal | Decimal | Description
(default) | 0x00000000 | 0 | Always execute. Action may run twice if present in both sequence tables.
msidbCustomAction TypeFirstSequence | 0x00000100 | 256 | Execute once if present in both sequence tables. Skips action in execute sequence if UI sequence has run. No effect in UI sequence. Not affected by install service registration.
msidbCustomAction TypeOncePerProcess | 0x00000200 | 512 | Execute once per process if in both sequence tables. Skips action in execute sequence if UI sequence has been run in same process, for example both run in the client process. Used to prevent actions that modify the session state, such as property and database data, from running twice.
msidbCustomAction TypeClientRepeat | 0x00000300 | 768 | Execute only if running on client after UI sequence has run. The action runs only if the execute sequence is run on the client following UI sequence. May be used to provide either/or logic, or to suppress the UI related processing if already done for client session.

Note that to run a custom action during two different run modes, author two entries into the CustomAction table . For example, to have a custom action that calls a C/C++ dynamic link library (DLL) (Custom Action Type 1) both when the mode is MSIRUNMODE_SCHEDULED and MSIRUNMODE_ROLLBACK put two entries in the CustomAction table that call the same DLL but that have different numeric types. Include code that calls MsiGetMode to determine when to run which custom action.

See Also

Custom Action Reference, About Custom Actions, Using Custom Actions


Custom Action In-Script Execution Options

You can use the following option flags to specify the in-script execution of custom actions. These options copy the action code into the execution, rollback, or commit script. To set an option add the value in this table to the value in the Type field of the CustomAction table.

Note that the msidbCustomActionTypeInScript must be included with each of these options.

Constant | Hexadecimal | Decimal | Description
(none) | 0x00000000 | 0 | Immediate execution.
msidbCustomAction TypeInScript | 0x00000400 | 1024 | Queue for execution at scheduled point within script. This flag designates that this is a deferred execution custom action.
msidbCustomAction TypeInScript + msidbCustomAction TypeRollback | 0x00000400 + 0x00000100 | 1280 | Queue for execution at scheduled point within script. Execute only upon an installation rollback. This flag designates that this is a rollback custom action.
msidbCustomAction TypeInScript + msidbCustomAction TypeCommit | 0x00000400 + 0x00000200 | 1536 | Queue for execution at scheduled point within script. Execute only upon install commit. This flag designates that this is a commit custom action.
msidbCustomAction TypeInScript + msidbCustomAction TypeNoImpersonate | 0x00000400 + 0x00000800 | 3072 | Queue for execution at scheduled point within script. Execute with no user impersonation. Run in system context.

See Also

Custom Action Reference, About Custom Actions, Using Custom Actions


Custom Action Return Values

If the msidbCustomActionTypeContinue return processing option is not set, the custom action must return an integer status code from the following table.

Return value | Description
ERROR_FUNCTION_NOT_CALLED | Action not executed.
ERROR_SUCCESS | Completed actions successfully.
ERROR_INSTALL_USEREXIT | User terminated prematurely.
ERROR_INSTALL_FAILURE | Unrecoverable error occurred.
ERROR_NO_MORE_ITEMS | Skip remaining actions, not an error.

Note that custom actions that are executable files must return a value of 0 for success. The installer interprets any other return value as failure. To ignore return values, set the msidbCustomActionTypeContinue bit flag in the Type field of the CustomAction table.

For more information about the msidbCustomActionTypeContinue option and other return processing options, see Custom Action Return Processing Options .


Return Values of JScript and VBScript Custom Actions

Custom actions written in JScript or VBScript can call an optional function. These functions must return one of the following values.

Return value | Value | Description
msiDoActionStatusNoAction | 0 | Action not executed.
msiDoActionStatusSuccess | IDOK = 1 | Action completed successfully.
msiDoActionStatusUserExit | IDCANCEL = 2 | Premature termination by user.
msiDoActionStatusFailure | IDABORT = 3 | Unrecoverable error. Returned if there is an error during parsing or execution of the Jscript or VBScript.
msiDoActionStatusSuspend | IDRETRY = 4 | Suspended sequence to be resumed later.
msiDoActionStatusFinished | IDIGNORE = 5 | Skip remaining actions. Not an error.


Properties

Properties are global variables that the Microsoft® Windows® Installer uses during an installation. The following sections describes the properties used by the installer.

  • About Properties
  • Using Properties
  • Property Reference

The term "property" also refers to an attribute of an automation object. See Automation Interface.


About Properties

The Microsoft® Windows® Installer uses three categories of global variables during an installation:

  • Private properties: The installer uses private properties internally and their values must be authored into the installation database or set to values determined by the operating environment.
  • Public properties: Public properties can be authored into the database and changed by a user or system administrator on the command line, by applying a transform, or by interacting with an authored user interface.
  • Restricted public properties: For security purposes, the author of an installation package can restrict the public properties a user can change.

Not all properties need to be defined in every package, there is a small set of required properties that must be defined in every package. The installer sets the values of properties in a particular order of precedence.

Private Properties

Public Properties

Restricted Public Properties

Required Properties

Order of Property Precedence

See Also

Using Properties, Property Reference


Private Properties

Private properties are used internally by the installer and their values must be entered into the database by the author of the installation package or set by the installer during the installation to values determined by the operating environment. The only way a user can interact with private properties is through Control Events in the package's authored user interface. Private property names must include lowercase letters. See Restrictions on Property Names.

Private properties commonly describe the operating environment. For example, if the installation is run on a Windows platform, the installer sets the WindowsFolder property to the value specified in the Property table.

Private property values cannot be overridden at a command line. The only way to clear a private property from an installation is to leave it out of the Property table. You also cannot set a private property in the user interface phase of the installation and then pass the value to the execution phase.

For a list of all the standard private properties used by the installer see Property Reference. You can define a custom private property by entering the property's name and initial value in the Property table. Private property names must always include lowercase letters.

See Also

Public Properties


Public Properties

Public properties can be authored into the installation database in the same way as private properties. In addition, the values of public properties can be changed by a user or system administrator by setting the property on the command line, by applying a transform, or by interacting with an authored user interface. Public property names cannot contain lowercase letters. See Restrictions on Property Names.

Public properties are commonly set by users during the installation. For example, the public property INSTALLLEVEL property can be specified at the command line used to launch the installation or chosen by using an authored user interface.

Public property values can be overridden either at a command line, by using a standard or custom action, by applying a transform, or by having the user interact with an authored user interface. To clear a public property in the property table, leave it out of the table. Properties that are to be set by the user interface during the installation and then passed to the execution phase of the installation must be public.

For a list of the standard public properties used by the installer see Property Reference. An author can also define a custom public property by entering the property's name and an initial value into the Property table. All public properties can be overridden by all users if any of the following conditions are true.

  • The system is Windows 95 or Windows 98.
  • The user is a system administrator.
  • The per-machine EnableUserControl policy is set to 1. See System Policy.
  • The EnableUserControl property is set to 1.
  • This is an unmanaged installation that is not being done with elevated privileges.

If none of the above conditions are true, the installer defaults to limiting which public properties can be overridden by a user that is not a system administrator. See Restricted Public Properties.


Restricted Public Properties

In the case of a managed installation, the package author may need to limit which public properties are passed to the server side and can be changed by a user that is not a system administrator. Some restrictions are commonly necessary to maintain a secure environment when the installation requires the installer to use elevated privileges. If all of the following conditions are met, a user that is not a system administrator can only override an approved list of restricted public properties.

  • The system is Windows NT/Windows 2000.
  • The user is not a system administrator.
  • The application or product is being installed with elevated privileges.

If all of the above conditions are true, the installer defaults to the following list of restricted public properties that can be changed by any user.

ACTION

AFTERREBOOT

ALLUSERS

EXECUTEACTION

EXECUTEMODE

FILEADDDEFAULT

FILEADDLOCAL

FILEADDSOURCE

INSTALLLEVEL

INSTALLLEVEL

LIMITUI

LOGACTION

NOCOMPANYNAME

NOUSERNAME

PATCH

PRIMARYFOLDER

PROMPTROLLBACKCOST

REBOOT

REINSTALL

REINSTALLMODE

RESUME

SEQUENCE

SHORTFILENAMES

TRANSFORMS

TRANSFORMSATSOURCE

The author of an installation package can extend this default list to include additional public properties by using the SecureCustomProperties property.

Setting the EnableUserControl property or the EnableUserControl system policy extends the list to all public properties. All users can then change any public property.

The installer sets the RestrictedUserControl property whenever the list of public properties passed to the server by non-administrator users is restricted.

See Also

About Properties


Required Properties

There are five properties that are required for every installation.

  • ProductCode
  • ProductLanguage
  • Manufacturer
  • ProductVersion
  • ProductName

See Also

About Properties


Order of Property Precedence

The installer sets properties using the following order of precedence. A property value in this list can override a value that comes after it and be overridden by a value coming before it in the list.

  1. Properties specified by the operating environment.
  2. Public properties set on the command line.
  3. Public properties listed by the AdminProperties property set during an administrative installation .
  4. Public or private properties set during the application of a transform.
  5. Public or private property that set by authoring the Property table of the .msi file.

See Also

About Properties


Using Properties

The following sections describe using the built-in installer properties and additional properties defined by the package author. Properties can be either public properties or private properties. Every property that needs to be defined upon initialization of the installer must have its name and initial value listed in the Property table. Properties having a Null value are not listed in the Property table. You can get or set properties from programs and custom actions and set public properties from the command line. The installation process can be modified by using properties in conditional statements.

Restrictions on Property Names

Initialization of Property Values

Getting and Setting Properties

Using Properties in Conditional Statements

See Also

About Properties, Property Reference

Note Do not use properties for passwords or other information that must remain secure. The installer may write the value of a property authored into the Property table, or created at runtime, into a log or the system registry.


Restrictions on Property Names

All property names must follow these restrictions.

  • A property name is an Identifier, which is a text string that must begin with either a letter or an underscore. Identifiers and property names may contain letters, numerals, underscores, or periods; but cannot begin with a numeral or period.
  • Public property names cannot contain lowercase letters.
  • Private property names must contain some lowercase letters.
  • Property names prefixed with % represent system and user environment variables. These are never entered into the Property table. The permanent settings of environment variables can only be modified using the Environment Table.

See Also

Using Properties


Initialization of Property Values

It is recommended that all properties to be used by the installation be entered into the Property table with an initial value. The installer sets the properties to these values at the launch of the installation. Properties for which a blank is an acceptable value and properties built into the installer do not need to be initialized.

See Also

Using Properties, Getting and Setting Properties


Getting and Setting Properties

To use properties in your installation, you can get and set property values from programs using MsiGetProperty and MsiSetProperty and include as part of conditional statements in the installation database.

  • To obtain a current property, call the MsiGetProperty function.
  • To obtain the current installation state, call the MsiGetMode function.
  • To obtain the language for the current installation, call the MsiGetLanguage function.
  • To set a property, call the MsiSetProperty function.
  • To set the installation state, call the MsiSetMode function.
  • To clear a property (setting it to Null), set the property's value to an empty string: "".

See Also

Using Properties, Setting Public Property Values on the Command Line, Clearing an Installer Property


Setting Public Property Values on the Command Line

To set a public property to a literal string value, included the string between quotation marks.

PROPERTY = "string"

To clear a public property at a command line (setting it to Null), set the property's value to an empty string.

PROPERTY="".

See Also

Using Properties, Getting and Setting Properties


Clearing an Installer Property

To clear a property (setting it to Null), set the property's value to an empty string: "".

See Also

Using Properties, Getting and Setting Properties


Using Properties in Conditional Statements

The logical value of a property that has been set is True. To determine whether a property is set without actually getting its value, test the logical expression "MyProperty" or "Not MyProperty". When the property MyProperty is set, the former evaluates as True and the latter as False.

One or more properties can be combined with operators to form logical expressions used in a conditional statements. For more information about the operators that can be used in conditional statements, see Conditional Statement Syntax.

A conditional statement using properties can be entered into the Condition column of the Condition table to modify the selection state of any entry in the Feature table.

Conditional statements with one or more properties are commonly used in the Condition column of database tables.

The following tables each have a column for conditional expressions:

Condition table
ControlEvent table
LaunchCondition table
InstallUISequence table
InstallExecuteSequence table
ControlCondition table
AdminExecuteSequence table
AdminExecuteSequence table
AdvtExecuteSequence table
AdminUISequence table

Note that the six action sequence tables have fields for a condition. If the conditional expression in this field evaluates to False, the installer skips that action.

For more information, see Using a Sequence Table or Using Properties.


Property Reference

This section lists the properties defined by the Microsoft® Windows® Installer. Additional properties can be specified by authored data or custom actions. Properties with names containing no lowercase letters are public properties and can be specified on the command line.

Component Location Properties

Configuration Properties

Date, Time Properties

Feature Installation Options Properties

Hardware Properties

Installation Status Properties

Operating System Properties

Product Information Properties

Summary Information Update Properties

System Folder Properties

User Information Properties

Obtaining Context Information for Deferred Execution Custom Actions


Component Location Properties

The following list provides links to more information about the component location properties.

Property name | Brief description of property
SourceDir | Root directory containing the source files.
TARGETDIR | Specifies the root destination directory for the installation. During an administrative installation this property is used as the location to copy the installation package.


Feature Installation Options Properties

The following list provides links to more information about the feature installation options properties.

Property name | Brief description of property
ADDDEFAULT | List of features to be installed in their default configuration.
ADDLOCAL | List of features to be installed locally.
ADDSOURCE | List of features to be run from source.
ADVERTISE | List of features to be advertised.
COMPADDLOCAL | List of component IDs to be installed locally.
COMPADDSOURCE | List of component IDs to run from source media.
FILEADDDEFAULT | List of file keys of files that are to be installed in their default configuration.
FILEADDLOCAL | List of file keys of the files to be run locally.
FILEADDSOURCE | List of file keys to be run from the source media.
PATCH | Setting this property applies a patch.
REINSTALL | List of features to be reinstalled.
REINSTALLMODE | A string containing letters that specify the type of reinstall to perform.
REMOVE | List of features to be removed.


Configuration Properties

The following list provides links to more information about other configurable properties.

Property name | Brief description of property
ACTION | Initial action called after the installer is initialized.
ALLUSERS | Determines where configuration information will be stored.
ARPAUTHORIZEDCDFPREFIX | URL of the update channel for the application.
ARPCOMMENTS | Provides Comments for the Add/Remove Control Panel.
ARPCONTACT | Provides Contact for the Add/Remove Control Panel.
ARPINSTALLLOCATION | Fully qualified path to the application's primary folder.
ARPNOMODIFY | Disables functionality that would modify the product.
ARPNOREMOVE | Disables functionality that would remove the product.
ARPNOREPAIR | Disables the Repair button in the Programs Wizard.
ARPPRODUCTICON | Specifies the primary icon for the installation package.
ARPREADME | Provides ReadMe for the Add/Remove Control Panel.
ARPSIZE | Estimated size of the application in kilobytes.
ARPSYSTEMCOMPONENT | Prevents display of application in Add/Remove programs list.
ARPURLINFOABOUT | URL for application's home page.
ARPURLUPDATEINFO | URL for application update information.
AVAILABLEFREEREG | Registry space in KB required by the application. Used by AllocateRegistrySpace action.
CCP_DRIVE | The root path for any of the qualifying products for CCP.
DefaultUIFont | Default font style used for controls.
DISABLEADVTSHORTCUTS | Set to disable the generation certain shortcuts supporting installation-on-demand.
DISABLEMEDIA | Prevents the installer from registering media sources, such as a CD-ROMs, as valid sources for the product.
DISABLEROLLBACK | Disables rollback for the current configuration.
EXECUTEACTION | Top-level action initiated by the ExecuteAction action.
EXECUTEMODE | Mode of execution performed by the installer.
FASTOEM | Improves installation performance under specific OEM scenarios.
INSTALLLEVEL | Initial "level" at which features will be installed.
LIMITUI | UI level capped as Basic.
LOGACTION | List of action names that will be logged.
MEDIAPACKAGEPATH | This property must be set to the relative path if the installation package is not located at the root of the CD-ROM.
PRIMARYFOLDER | Allows the author to designate a "primary" folder for the installation. Used to determine the values for the PrimaryVolumePath, PrimaryVolumeSpaceAvailable, PrimaryVolumeSpaceRequired, and PrimaryVolumeSpaceRemaining properties.
Privileged | Runs an installation with elevated privileges.
PROMPTROLLBACKCOST | Action if there is insufficient disk space for the installation.
REBOOT | Force or suppress rebooting.
REBOOTPROMPT | Suppresses the display of prompts for reboots to the user. Any reboots that are needed happen automatically.
ROOTDRIVE | Default drive for the install.
SEQUENCE | A table having the sequence table schema.
SHORTFILENAMES | Causes short file names to be used.
TRANSFORMS | List of transforms to be applied to the database.
TRANSFORMSATSOURCE | Informs the installer that the transforms for the product reside at the source.
TRANSFORMSSECURE | Setting the TRANSFORMSECURE property to 1 informs the installer that transforms are to be cached locally on the user's computer in a location where the user does not have write access.


User Information Properties

The following list provides links to more information about user-supplied information.

Property name | Brief description of property
AdminProperties | List of properties set during an administration installation.
COMPANYNAME | Organization of user performing the installation.
PIDKEY | Part of the Product ID entered by user.
ProductID | Full Product ID after a successful validation.
UserLanguageID | Default language identifier of the current user.
USERNAME | User performing the installation.


Product Information Properties

The following list provides links to more information about product-specific properties specified in the property table.

Property name | Brief description of property
ARPHELPLINK | Internet address, or URL, for technical support.
ARPHELPTELEPHONE | Technical support phone numbers.
DiskPrompt | String displayed by a message box prompting for a disk.
IsAdminPackage | Set to 1 if the current installation is running from a package created through an administrative installation.
LeftUnit | Places units to the left of the number.
Manufacturer | Name of the application's manufacturer. (REQUIRED)
PIDTemplate | String used as a template for the PIDKEY property.
ProductCode | A unique identifier for the particular product release. (REQUIRED)
ProductName | Human-readable name of the application. (REQUIRED)
ProductState | Set to the installed state of a product.
ProductVersion | String format of the product version as a numeric value. (REQUIRED)
UpgradeCode | A GUID representing a related set of products.


System Folder Properties

The following list provides links to more information about system folders set by the installer at setup.

Property name | Brief description of property
AdminToolsFolder | Full path to directory containing administrative tools for an individual user.
AppDataFolder | Full path to the Application Data folder for the current user.
CommonAppDataFolder | Full path to Application data for all users.
CommonFiles64Folder | Full path to the predefined 64-bit Common Files folder.
CommonFilesFolder | Full path to the Common Files folder for the current user.
DesktopFolder | Full path to the Desktop folder.
FavoritesFolder | Full path to the Favorites folder for the current user.
FontsFolder | Full path to the Fonts folder.
LocalAppDataFolder | Full path to directory that serves as a data repository for local (non-roaming) applications.
MyPicturesFolder | Full path to the MyPicturesFolder.
PersonalFolder | Full path to the Personal folder for the current user.
ProgramFiles64Folder | Full path of the predefined 64-bit Program Files folder.
ProgramFilesFolder | Full path of the predefined 32-bit Program Files folder.
ProgramMenuFolder | Full path to the Program Menu folder.
SendToFolder | Full path to the SendTo folder for the current user.
StartMenuFolder | Full path to the Start menu folder.
StartupFolder | Full path to the Startup folder.
System16Folder | Full path to folder for 16-bit system DLLs.
System64Folder | Full path to the predefined System64 folder.
SystemFolder | Full path to the System folder.
TempFolder | Full path to the Temp folder.
TemplateFolder | Full path to the Template folder for the current user.
WindowsFolder | Full path to the Windows folder.
WindowsVolume | The volume of the Windows folder.


Operating System Properties

The following list provides links to more information about operating system properties set by the installer at startup.

Property name | Brief description of property
AdminUser | Set on Microsoft® Windows NT®/Windows® 2000 if the user has administrator privileges.
ComputerName | Computer name of the current system.
LogonUser | User name for the user currently logged on.
MsiNTProductType | Indicates the Windows product type. Only available with Windows Installer version 1.5 and later versions.
MsiNTSuiteBackOffice | On Windows 2000 and later operating systems, the installer sets this property to 1 if and only if Microsoft BackOffice components are installed. Only available with Windows Installer version 1.5 and later versions.
MsiNTSuiteDataCenter | On Windows 2000 and later operating systems, the installer sets this property to 1 if and only if Windows 2000 DataCenter Server is installed. Only available with Windows Installer version 1.5 and later versions.
MsiNTSuiteEnterprise | On Windows 2000 and later operating systems, the installer sets this property to 1 if and only if Windows® 2000 Advanced Server is installed. Only available with Windows Installer version 1.5 and later versions.
MsiNTSuiteSmallBusiness | On Windows 2000 and later operating systems, the installer sets this property to 1 if and only if Microsoft Small Business Server is installed. Only available with Windows Installer version 1.5 and later versions.
MsiNTSuiteSmallBusinessRestricted | On Windows 2000 and later operating systems, the installer sets this property to 1 if and only if Microsoft Small Business Server is installed with the restrictive client license in force. Only available with Windows Installer version 1.5 and later versions.
MsiNTSuitePersonal | On Windows 2000 and later operating systems, the installer sets this property to 1 if and only if the operating system is Workstation Personal. Only available with Windows Installer version 1.5 and later versions.
OLEAdvtSupport | Set if OLE supports the Microsoft Windows Installer.
RedirectedDLLSupport | The installer sets the RedirectedDLLSupport property if the system performing the installation supports Isolated Components.
RemoteAdminTS | The installer sets the RemoteAdminTS property when the system is a remote administration server using Terminal Services.
ServicePackLevel | The version number of the operating system service pack.
ServicePackLevelMinor | The minor version number of the operating system service pack.
SharedWindows | Set when the system is operating as Shared Windows.
ShellAdvtSupport | Set if the shell supports feature advertising.
SystemLanguageID | Default language identifier for the system.
TerminalServer | Set when the system is a server with Windows Terminal Server.
TTCSupport | Indicates if the operating system supports using .TTC (true type font collections) files.
Version9X | Version number for the Windows operating system.
VersionDatabase | Numeric database version of the current installation.
VersionNT | Version number for the Windows NT/Windows 2000 operating system.
VersionNT64 | Version number for the Windows NT/Windows 2000 operating system if the system is running on a 64-bit computer.
WindowsBuild | Build number of the operating system.


Hardware Properties

The following list provides links to more information about hardware properties set by the installer at startup.

Property name | Brief description of property
Alpha | Numeric processor level if running on an Alpha processor. Note The Alpha platform is not supported by Windows Installer version 1.1 or later.
BorderSide | The width, in pixels, of the window borders.
BorderTop | The height, in pixels, of the window borders.
CaptionHeight | Height, in pixels, of normal caption area.
ColorBits | Number of adjacent color bits for each pixel.
Intel | Numeric processor level if running on an Intel processor.
Intel64 | Numeric processor level if running on an IA-64 processor.
PhysicalMemory | Size of the installed RAM in megabytes.
ScreenX | Width, in pixels, of the screen.
ScreenY | Height, in pixels, of the screen.
TextHeight | The height of characters in logical units.
VirtualMemory | Amount of available page file space in megabytes.


Installation Status Properties

The following list provides links to more information about status properties that are updated by the installer during installation.

Property name | Brief description of property
AFTERREBOOT | Indicates current installation follows a reboot invoked by the ForceReboot action.
CostingComplete | Indicates whether disk space costing has completed.
Installed | Indicates that a product is already installed.
NOCOMPANYNAME | Suppresses the automatic setting of the USERNAME property.
NOUSERNAME | Suppresses the automatic setting of the USERNAME property.
OutOfDiskSpace | Insufficient disk space to accommodate the installation.
OutOfNoRbDiskSpace | Insufficient disk space with rollback turned off.
Preselected | Features are already selected.
PrimaryVolumePath | The Installer sets the value of this property to the path of the volume designated by the PRIMARYFOLDER property.
PrimaryVolumeSpaceAvailable | The Installer sets the value of this property to a string representing the total number of bytes available on the volume referenced by the PrimaryVolumePath property.
PrimaryVolumeSpaceRemaining | The Installer sets the value of this property to a string representing the total number of bytes remaining on the volume referenced by the PrimaryVolumePath property if all the currently selected features were installed.
PrimaryVolumeSpaceRequired | The Installer sets the value of this property to a string representing the total number of bytes required by all currently selected features on the volume referenced by the PrimaryVolumePath property.
ProductLanguage | Numeric language identifier (LANGID) for the database. (REQUIRED)
ReplacedInUseFiles | Set if the installer installs over a file that is being held in use.
RESUME | Resumed installation.
RollbackDisabled | The installer sets this property whenever rollback is disabled.
UILevel | Indicates the user interface level.
UpdateStarted | Set when changes to the system have begun for this install.


Date, Time Properties

The Date and Time properties are live properties set by the installer whenever the data is extracted.

Property name | Brief description of property
Date | The current date.
Time | The current time.


Summary Information Update Properties

The following properties are only set by transforms in .msp files used to update the summary information stream of an administrative image.

Property name | Brief description of property
PATCHNEWPACKAGECODE | The value of this property is written to the Revision Number Summary Property.
PATCHNEWSUMMARYCOMMENTS | The value of this property is written to the Comments Summary Property.
PATCHNEWSUMMARYSUBJECT | The value of this property is written to the Subject Summary Property.


ACTION Property

The ACTION property can be set to the following values .

ACTION property value | Action
INSTALL | INSTALL Action
ADVERTISE | ADVERTISE Action
ADMIN | ADMIN Action

The ACTION property determines which action to perform if a Null action name is supplied to MsiDoAction or the DoAction Method. If no value is defined for the ACTION property, the installer calls the INSTALL Action.


ADVERTISE Property

The value of the ADVERTISE property is a list of features delimited by commas that are to be advertised. The features must be present in the Feature column of the Feature table. To install all features as advertised, use ADVERTISE=All on the command line. Do not enter ADVERTISE=All into the Property table because this generates an advertised the package that cannot be installed or removed.

Remarks

Note that feature names are case-sensitive.

The installer always evaluates the following properties in the following order.

  1. ADDLOCAL
  2. REMOVE
  3. ADDSOURCE
  4. ADDDEFAULT
  5. REINSTALL
  6. ADVERTISE
  7. COMPADDLOCAL
  8. COMPADDSOURCE
  9. FILEADDLOCAL
  10. FILEADDSOURCE
  11. FILEADDDEFAULT

For example, if the command line specifies: ADDLOCAL=ALL, ADDSOURCE = MyFeature, all the features are first set to run-local and then MyFeature is set to run-from-source. If the command line is: ADDSOURCE=ALL, ADDLOCAL=MyFeature, first MyFeature is set to run-local, and then when ADDSOURCE=ALL is evaluated, all features (including MyFeature) are reset to run-from-source.

The installer sets the Preselected property to a value of "1" during the resumption of a suspended install or when any of the above properties are specified on the command line.


ADDDEFAULT Property

The value of the ADDDEFAULT property is a list of features delimited by commas that are to be installed in their default configuration. The features must be present in the Feature column of the Feature table. To install all features in their default configurations, use ADDDEFAULT=All on the command line.

A feature listed in the ADDDEFAULT property is installed in the same installation state as if the user had requested an installation-on-demand of the feature. The state is determined by which bits are set for the feature in the Attributes column of the Feature table, and which bits are set for the feature's components in the Attributes column of the Component table.

Remarks

Note that the feature names are case-sensitive.

The installer always evaluates the following properties in the following order.

  1. ADDLOCAL
  2. REMOVE
  3. ADDSOURCE
  4. ADDDEFAULT
  5. REINSTALL
  6. ADVERTISE
  7. COMPADDLOCAL
  8. COMPADDSOURCE
  9. FILEADDLOCAL
  10. FILEADDSOURCE
  11. FILEADDDEFAULT

For example, if the command line specifies: ADDLOCAL=ALL, ADDSOURCE = MyFeature, all the features are first set to run-local and then MyFeature is set to run-from-source. If the command line is: ADDSOURCE=ALL, ADDLOCAL=MyFeature, first MyFeature is set to run-local, and then when ADDSOURCE=ALL is evaluated, all features (including MyFeature) are reset to run-from-source.

The installer sets the Preselected property to a value of "1" during the resumption of a suspended install or when any of the above properties are specified on the command line.


ADDLOCAL Property

The value of the ADDLOCAL property is a list of features delimited by commas that are to be installed locally. The features must be present in the Feature column of the Feature table. To install all features locally, use ADDLOCAL=All on the command line. Do not enter ADDLOCAL=All into the Property table because this generates an locally installed package that cannot be correctly removed.

Remarks

Note that feature names are case-sensitive. If the SourceOnly bit flag is set in the Attributes column of the Component table for a component of a feature in the list, that component is installed as run from source.

The installer always evaluates the following properties in the following order.

  1. ADDLOCAL
  2. REMOVE
  3. ADDSOURCE
  4. ADDDEFAULT
  5. REINSTALL
  6. ADVERTISE
  7. COMPADDLOCAL
  8. COMPADDSOURCE
  9. FILEADDLOCAL
  10. FILEADDSOURCE
  11. FILEADDDEFAULT

For example, if the command line specifies: ADDLOCAL=ALL, ADDSOURCE = MyFeature, all the features are first set to run-local and then MyFeature is set to run-from-source. If the command line is: ADDSOURCE=ALL, ADDLOCAL=MyFeature, first MyFeature is set to run-local, and then when ADDSOURCE=ALL is evaluated, all features (including MyFeature) are reset to run-from-source.

The installer sets the Preselected property to a value of "1" during the resumption of a suspended install or when any of the above properties are specified on the command line.


ADDSOURCE Property

The value of the ADDSOURCE property is a list of features delimited by commas that are to be installed to run from source. The features must be present in the Feature column of the Feature table. To install all features as run from source, use ADDSOURCE=All on the command line. Do not enter ADDSOURCE=All into the Property table because this generates a run-from-source package that cannot be correctly removed.

Remarks

Note that the feature names are case-sensitive. If the LocalOnly bit flag is set in the Attributes column of the Component table for a component of a feature in the list, that component is installed to run locally.

The installer always evaluates the following properties in the following order.

  1. ADDLOCAL
  2. REMOVE
  3. ADDSOURCE
  4. ADDDEFAULT
  5. REINSTALL
  6. ADVERTISE
  7. COMPADDLOCAL
  8. COMPADDSOURCE
  9. FILEADDLOCAL
  10. FILEADDSOURCE
  11. FILEADDDEFAULT

For example, if the command line specifies: ADDLOCAL=ALL, ADDSOURCE = MyFeature, all the features are first set to run-local and then MyFeature is set to run-from-source. If the command line is: ADDSOURCE=ALL, ADDLOCAL=MyFeature, first MyFeature is set to run-local, and then when ADDSOURCE=ALL is evaluated, all features (including MyFeature) are reset to run-from-source.

The installer sets the Preselected property to a value of "1" during the resumption of a suspended install or when any of the above properties are specified on the command line.


AdminProperties Property

The AdminProperties property is a semicolon delimited list of properties set at the time of an administrative installation. When users subsequently install from the administrative image, their installation uses the values of properties listed in AdminProperties, rather than the values in the .msi file.

Remarks

The property names in the list can be a mix of upper and lower case letters (private properties) or all upper case (public properties).

This property must never end with a semicolon.

See Also

About Properties


AdminToolsFolder Property

Full path to the file system directory that stores administrative tools for a user. Microsoft® Management Console saves customized consoles to this directory and roams with the user. If the ALLUSERS property is set, this property points to the file system directory containing the administrative tools for all users of the computer.

Remarks

This property is not available with Windows Installer version 1.0.


AdminUser Property

The installer sets the AdminUser property on Windows NT/Windows 2000 if the user has administrator privileges. This property is always set on Windows 95 and Windows 98.

For more information, see Privileged property. In some cases, this property should be used instead of AdminUser in conditional statements. For example, the installer only sets the AdminUser property if the user is an administrator. The installer sets the Privileged property if the user is an administrator or if policy enables the user to install with elevated privileges. For details, see How do I install a package with elevated privileges as a non-admin?


AFTERREBOOT Property

The installer sets the AFTERREBOOT property to 1 after a reboot invoked by the ForceReboot action. The installer adds AFTERREBOOT=1 to the command line run immediately after the reboot.

Remarks

The ForceReboot action must always be used with a conditional statement such that the installer triggers a reboot only when necessary. A reboot might be required if a particular file was replaced or a particular component was installed. The case is different for each product and a custom action might be needed to determine whether a reboot is needed. The condition on the ForceReboot action commonly makes use of the AFTERREBOOT property.

See Also

System Reboots


ALLUSERS Property

The ALLUSERS property determines where the configuration information of the installed application is stored. This property is used with the DesktopFolder property, ProgramMenuFolder property, StartMenuFolder property, and StartupFolder property.

The following tables illustrate how the property affects the application installation when combined with the access privileges of the user and the type of operating system.

Windows NT/Windows 2000 | ALLUSERS = NULL | ALLUSERS = 1 | ALLUSERS =2
User access privileges. | Per-user installation using folders in user's personal profile. | Not valid; returns an error stating the user does not have enough access privileges to install application. | Per-user installation using folders in user's personal profile.
Administrator access privileges. | Per-user installation using folders in user's personal profile. | Per-machine installation using folders in "All Users" profile. | Per-machine installation using folders in "All Users" profile.

Default Value

If ALLUSERS is not set, the installer does a per-user installation.

Remarks

It is strongly recommended that developers do not author packages that set the ALLUSERS property using a dialog or custom action on Windows 95 or Windows 98. An upgrade may fail on Windows 95/98 if the ALLUSERS property is set using a dialog or a custom action. On Windows 95/98, the installer ignores any attempt to set ALLUSERS by either the command line or by the Property table. The ALLUSERS property can however still be set using a dialog or a custom action, and this causes upgrades of that install to fail.

For details, see also How do I specify a per-user or per-machine installation?


Alpha Property

The Alpha property is defined only if running on an Alpha processor. The installer sets it to the value of the numeric processor level.

Note The Alpha platform is not supported by Windows Installer version 1.1.


AppDataFolder Property

The installer sets the AppDataFolder property to the full path to the Application Data folder for the current user.

Remarks

The full path to the Application Data folder for the current user can be found as the AppData value written under the following registry key: HKCU\Software\Microsoft\Windows\CurrentVersion\Explorer\Shell Folders.


ARPAUTHORIZEDCDFPREFIX Property

The ARPAUTHORIZEDCDFPREFIX property is set to the URL of the update channel for the application.


ARPCOMMENTS Property

The ARPCOMMENTS property provides the Add/Remove Control Panel Comments that are written under the Uninstall Registry Key. This property can be set by the command line or a transform.


ARPCONTACT Property

The ARPCONTACT property provides the Add/Remove Control Panel Contact that is written under the Uninstall Registry Key. This property can be set by the command line or a transform.


ARPHELPLINK Property

The ARPHELPLINK property is the Internet address for technical support. Product maintenance applets display this value.


ARPHELPTELEPHONE Property

The ARPHELPTELEPHONE property is technical support phone numbers. Product maintenance applets display this value.


ARPINSTALLLOCATION Property

The ARPINSTALLLOCATION property is the full path to the application's primary folder.

Remarks

Typically needs to be set by a custom action.


ARPNOREPAIR Property

Set the ARPNOREPAIR property to disable the Repair button in the Programs Wizard. For more information, see Getting and Setting Properties.


ARPPRODUCTICON Property

The ARPPRODUCTICON property specifies the foreign key to the Icon table, which is the primary icon for the Windows Installer package.


ARPREADME Property

The ARPREADME property provides the Add/Remove Control Panel ReadMe for the application that is written under the Uninstall Registry Key. This property can by set by the command line or a transform.


ARPSIZE Property

The ARPSIZE property is the estimated size of the application in kilobytes.


ARPSYSTEMCOMPONENT Property

Setting the ARPSYSTEMCOMPONENT property to 1 using the command line or a transform prevents the application from being displayed in the Add/Remove programs list.


ARPURLINFOABOUT Property

The ARPURLINFOABOUT property is the URL for the link to the publishers home page or the application's home page.


ARPURLUPDATEINFO Property

The ARPURLUPDATEINFO property is the URL for the link used to update information on the application.


ARPNOMODIFY Property

Setting the ARPNOMODIFY property disables Add/Remove functionality in Control Panel that modifies the product. For Windows 2000, this disables the Modify button for the product in Add/Remove Programs in Control Panel. On earlier operating systems, clicking the Add/Remove button uninstalls the product rather than entering the maintenance mode wizard.

If the ARPNOMODIFY property is set, the RegisterProduct action writes the value "NoModify" under the registry key: HKLM\Software\Microsoft\Windows\CurrentVersion\Uninstall\{product key}.

If the ARPNOMODIFY property is set and the ARPNOREMOVE property is not set, the RegisterProduct action also writes the UninstallString value under this key. The UnistallString value is a command line for removing the product, rather than reconfiguring the product.

Remarks

For example, this property can be set during a customization transform to prevent users from changing an administrator's customization.


ARPNOREMOVE Property

Setting the ARPNOREMOVE property disables the Add/Remove functionality in Control Panel that removes the product. For Windows 2000, this disables the Remove button for the product from the Add/Remove Programs in Control Panel. For earlier operating systems, this has the effect of removing the product from the list of installed products on the Add/Remove Programs in Control Panel.

If the ARPNOREMOVE property is set, the RegisterProduct action writes the value "NoRemove" under the registry key: HKLM\Software\Microsoft\Windows\CurrentVersion\Uninstall\{product key}.

Setting the ARPNOREMOVE property prevents the UninstallString value from being written under this key. The UnistallString value is a command line for removing the product, rather than reconfiguring the product.

Remarks

For example, this property can be set during a customization transform to prevent users from removing an administrator customization.


BorderSide Property

The installer sets the BorderSide property to the width of the window borders in pixels.


BorderTop Property

The installer sets the BorderTop property to the height of the window borders in pixels.


AVAILABLEFREEREG Property

The AVAILABLEFREEREG property specifies in kilobytes the total free space available in the registry after calling the AllocateRegistrySpace action.

The maximum value of the AVAILABLEFREEREG property is 2000000 kilobytes.

This property is set only on Microsoft® Windows NT® version 4.0 and Microsoft Windows® 2000.

Remarks

The AVAILABLEFREEREG property must be set to a value large enough to ensure sufficient space in the registry for all registration information added by the installation. The minimum value required to ensure sufficient space depends on where the AllocateRegistrySpace action is located in the action sequence because the installer automatically increases the space as needed when registering information in the Registry, Class, SelfReg, Extension, MIME, and Verb tables. The installer does not increase the total registry space to the amount specified by AVAILABLEFREEREG until reaching AllocateRegistrySpace in the action sequence.

If AllocateRegistrySpace is one of the first actions in the action sequence, AVAILABLEFREEREG should be set to the total space required by the registration information in the Registry table, Class table, TypeLib table, SelfReg table, Extension table, MIME table, Verb table, custom actions registration, self registration, and any other registry information written during the installation. The value of AVAILABLEFREEREG is the total amount of information added by the installation and ensures sufficient space in all cases. This is also the most common case.

If the AllocateRegistrySpace action can be authored into the action sequence after all standard actions that write registration data, such as WriteRegistryValues and RegisterClassInfo, the value of AVAILABLEFREEREG needs only be set to the space needed to register custom actions, register type libraries, and any other information not yet registered through the tables.


CaptionHeight Property

The installer sets the CaptionHeight property to the height, in pixels, of the window caption area.


CCP_DRIVE Property

The CCP_DRIVE property is set to the root path of the removable volume that is to be searched by RMCCPSearch. The RMCCPSearch action uses file signatures to validate that qualifying products are installed on a system before performing an upgrade installation.

This property is typically set via the user interface or a custom action. This property should be set before the RMCCPSearch action is run.


ColorBits Property

The installer sets the ColorBits property to the number of adjacent color bits for each pixel.


CommonFilesFolder Property

The installer sets the CommonFilesFolder property to the full path to the Common Files folder for the current user.

Remarks

The installer sets this property. For example, on 32-bit Windows, the value may be C:\Program Files\Common Files. On 64-bit Windows, the value may be C:\Program Files (x86)\Common Files.


COMPADDLOCAL Property

The value of the COMPADDLOCAL property is a list of component GUIDs from the ComponentId column of the Component table, delimited by commas, that are to be installed locally. The installer uses this list to determine which features are set to be installed locally, based on the specified components. For each listed component ID, the installer examines all features linked to that component through the FeatureComponents table, and installs the feature that requires the least amount of disk space to install. The components listed must be present in the Component column of the Component table.

Remarks

Note that the component names are case-sensitive. Also note that if the SourceOnly bit flag is set in the Attributes column of the Component table for a component, then the component is installed to run from source.

The installer always evaluates the following properties in the following order.

  1. ADDLOCAL
  2. REMOVE
  3. ADDSOURCE
  4. ADDDEFAULT
  5. REINSTALL
  6. ADVERTISE
  7. COMPADDLOCAL
  8. COMPADDSOURCE
  9. FILEADDLOCAL
  10. FILEADDSOURCE
  11. FILEADDDEFAULT

For example, if the command line specifies: ADDLOCAL=ALL, ADDSOURCE = MyFeature, all the features are first set to run-local and then MyFeature is set to run-from-source. If the command line is: ADDSOURCE=ALL, ADDLOCAL=MyFeature, first MyFeature is set to run-local, and then when ADDSOURCE=ALL is evaluated, all features (including MyFeature) are reset to run-from-source.

The installer sets the Preselected property to a value of "1" during the resumption of a suspended install or when any of the above properties are specified on the command line.


CommonFiles64Folder Property

The installer sets the CommonFiles64Folder property to the full path of the predefined 64-bit Common Files folder. The existing CommonFilesFolder Property is set to the corresponding 32-bit folder.

Remarks

The installer sets this property on 64-bit Windows. This property is not used on 32-bit Windows. When using 64-bit Windows, the value may be C:\Program Files\Common Files.


COMPADDSOURCE Property

The value of the COMPADDSOURCE property is a list of component GUIDs from the ComponentId column of the Component table, delimited by commas, that are to be installed to run from the source media. The installer uses this value to determine which features are set to be installed to run from source, based on the specified components. For each listed component ID, the installer examines all features linked (via the FeatureComponents table) to that component, and installs the feature that requires the least amount of disk space to install. The components listed must be present in the Component column of the Component table.

Remarks

Note that the component names are case-sensitive. Also note that if the LocalOnly bit flag is set in the Attributes column of the Component table for a component, then the component is installed to run locally.

The installer always evaluates the following properties in the following order:

  1. ADDLOCAL
  2. REMOVE
  3. ADDSOURCE
  4. ADDDEFAULT
  5. REINSTALL
  6. ADVERTISE
  7. COMPADDLOCAL
  8. COMPADDSOURCE
  9. FILEADDLOCAL
  10. FILEADDSOURCE
  11. FILEADDDEFAULT

For example, if the command line specifies: ADDLOCAL=ALL, ADDSOURCE = MyFeature, all the features are first set to run-local and then MyFeature is set to run-from-source. If the command line is: ADDSOURCE=ALL, ADDLOCAL=MyFeature, first MyFeature is set to run-local, and then when ADDSOURCE=ALL is evaluated, all features (including MyFeature) are reset to run-from-source.

The installer sets the Preselected property to a value of "1" during the resumption of a suspended install or when any of the above properties are specified on the command line.


COMPANYNAME Property

The COMPANYNAME property is the organization or company of the user performing the installation.

Default Value

A default value can be put in the Property table. If the COMPANYNAME property is not set, the installer sets it automatically using values from the registry.

Remarks

Set the NOCOMPANYNAME property to suppress the automatic setting of COMPANYNAME.


NOCOMPANYNAME Property

Set the NOCOMPANYNAME property to 1 to suppress the automatic setting of the COMPANYNAME property by the installer. This property is used by applications that need to collect the company name at the first-run.

Default Value

Not set. The installer sets the COMPANYNAME property automatically using values from the registry.


CommonAppDataFolder Property

Full path to the file directory containing application data for all users. A common path is C:\WINNT\Profiles\All Users\Application Data.

Remarks

This property is not available with Windows Installer version 1.0.


ComputerName Property

The ComputerName property is the computer name of the current system. The installer sets this property by a system call to GetComputerName.


CostingComplete Property

The CostingComplete property indicates whether the installer has completed disk space costing. This property can be used to author a dialog box triggered if costing has not been completed. The property is set dynamically during disk space costing and is set to 1 as soon as the costing is complete. This property is initialized to 0 by the CostFinalize action.

Remarks

For an example of how to author a "Please wait . . . " dialog box that pops up during disk space costing, see the section Authoring a Conditional "Please wait . . ." Message Box.


Date Property

The Date property is the current month, day, and year as a string of literal text.

Remarks

Because this is a text string, it cannot be used in conditional expressions.


VersionDatabase Property

The value of the VersionDatabase property is the numeric database version of the current installation.


DefaultUIFont Property

The DefaultUIFont property sets the default font style used for controls. To specify the default, set DefaultUIFont to one of the predefined styles in the TextStyle table in the Property table.

Remarks

The DefaultUIFont property of every installation package with a UI should be set in the Property table to one of the predefined styles listed in the TextStyle table. If this property is not specified, the installer uses the System font. This can cause the installer to improperly display text strings when the package's code page is different from the user's default UI code page.

The text and font style of a control can be set as described in Adding Controls and Text. If the character string listed in the Text column of the Control table or BBControl table does not specify the font style, the control uses the value of the DefaultUIFont property as the font style.


DesktopFolder Property

The installer sets the DesktopFolder property to the full path to the current user's Desktop folder. If an "All Users" profile exists and the ALLUSERS property is set, then this property is set to the folder in the "All Users" profile.

Remarks

Common values for this property are C:\Winnt\Profiles\[LogonUser]\Desktop\ (Windows NT/Windows 2000) and C:\Windows\Desktop\ (Windows 95 and Windows 98).


DISABLEMEDIA Property

Setting the DISABLEMEDIA property prevents the installer from registering any media source, such as a CD-ROM, as a valid source for the product. If browsing is enabled, however, a user may still browse to a media source.

Remarks

Note that the DISABLEMEDIA property has a different effect than setting the DisableMedia policy. Setting DISABLEMEDIA prevents the registration of any media source, and this also prevents the first time installation of an application from a media sources.

For details about securing the media sources of managed application against browsing and installation by non-administrative users, see Source Resiliency.

See Also

Source Resiliency


DISABLEROLLBACK Property

Setting the DISABLEROLLBACK property disables the rollback option for the current configuration. Set this property to 1 to prevent the installer from generating a rollback script and saving copies of deleted files during the installation.

Default Value

By default, rollback is enabled.

Remarks

Setting this property has the same effect as setting the DisableRollback policy value to 1. For more information about DisableRollback policy, see System Policy.

The installer sets the RollbackDisabled Property whenever the DISABLEROLLBACK property is set to 1.

It is recommended that rollback not be disabled unless necessary because doing so can result in partially installed applications being left behind on a user's computer.

See Also

System Policy, PromptRollbackCost property


RollbackDisabled Property

The installer sets the RollbackDisabled property when rollback has been disabled. RollbackDisabled is used by package authors who need to ensure that the installer has not disabled rollback. The RollbackDisabled property can be used in a conditional expression that effectively refuses to continue with the installation if RollbackDisabled property is set.

Default Value

By default, rollback is enabled.

Remarks

Because rollback and commit do not run while rollback is disabled, the installer cannot properly install a package that uses these types of custom actions in a transaction during the installation. In this case, the author of the package should include a condition using DisableRollback that prevents the installation from continuing if rollback is disabled.

The DisableRollback policy value can be set by an administrator as a part of assigning system policy. Administrators are advised to not disable rollback unless necessary. For more information about DisableRollback policy value, see System Policy.

See Also

Rollback Installation, System Policy, rollback custom actions, commit custom actions


DISABLEADVTSHORTCUTS Property

Setting the DISABLEADVTSHORTCUTS property disables the generation of shortcuts supporting installation-on-demand and advertisement. Setting this property specifies that these shortcuts should instead be replaced by regular shortcuts.

The shortcuts that support advertisement have the name of a feature, rather than a formatted file path of the form [#filekey], entered in the Target column of the Shortcut table. If this property is set and the feature is installed, the installer generates a regular shortcut to the feature.

This property is commonly used by administrators for users who roam between environments that do and do not support advertising. This property can be set by a transform, in the administrative stream, or in the Property table. If it is set using the command line or by a call to MsiSetProperty, then it must be reset again during each subsequent installation.

Default Value

By default, installation-on-demand shortcut generation is enabled.


DiskPrompt Property

The DiskPrompt property value holds a string displayed by a dialog box prompting for a disk. This string should include the name of the product and a placeholder for the text printed on the CD-ROM surface.

Advertised as a product property.

See Also

Authoring Disk Prompt Messages


EnableUserControl Property

If the EnableUserControl property is set to 1, then the installer can pass all public properties to the server side during a managed installation using elevated privileges. Setting this property has the same effect as setting the EnableUserControl system policy.

See Also

Restricted Public Properties, system policy


EXECUTEACTION Property

The EXECUTEACTION Property is set to determine which top-level action the ExecuteAction action initiates.

The top-level actions, such as the INSTALL action, ADVERTISE action, and ADMIN action set the EXECUTEACTION property to the name of the top-level action.


EXECUTEMODE Property

The EXECUTEMODE property specifies how the installer executes system updates. This property may be useful when it is necessary to run an installation without actually changing the system. The property can be set to None to disable updating operations such as the installation of files and registry values.

This property can have one of the following two values. The installer only examines the first letter of the value and is case insensitive.

None
No changes are made to the system. The installer runs the user interface and then queries the database.
Script
All changes to the system are made through script execution. This is the default mode.

Default Value

If this property is not defined, the execution mode defaults to Script.


FASTOEM Property

The FASTOEM property is designed to enable OEMs to reduce the time it takes to install Windows Installer applications for a specific scenario. Do not author the FASTOEM property into the Property Table.

The FASTOEM property is only applicable if all of these conditions are true:

  • The application is being installed on the same volume as the folder containing the source files.
  • The source files are deleted after the installation.
  • No user interface is displayed during the installation. The user interface level is none.
  • This is a per-machine installation.
  • There is enough space on the computer for a successful installation.
  • This is first time installation. The installation is not advertising, reinstalling, removing, or doing an administrative installation.
  • No features are installed to run from source.
  • The installation package contains no isolated components. Because isolated components require source files to remain located at the source, the FASTOEM property cannot currently be used with isolated components.

If all of the previous conditions are true, setting the FASTOEM property enables Windows Installer to improve performance by doing the following:

  • Move rather than copy files on the same volume. This does not guarantee that all files are moved rather than copied.
  • Omit this source from the application's source list so that subsequent reinstallation or maintenance installations default to the CD-ROM sources specified in the Media Table.
  • Streamline file costing.
  • Suppress progress messages sent from Windows Installer to the client.

The FASTOEM property is not supported with Windows Installer version 1.0 or version 1.1.

Remarks

Because no progress messages are sent when FASTOEM is set, it is recommended that authors manually write a value of 1800 for Timeout into the key HKLM\SoftWare\Policies\Microsoft\Windows\Installer\Timeout. Timeout is a REG_DWORD type.

To display the size of the application in Add/Remove Programs in the Windows 2000 Control Panel, you must manually write the value of EstimatedSize into the key HKLM\Software\Microsoft\Windows\CurrentVersion\Uninstall\<Product Code>. This is a REG_DWORD type and equals to the size of the application in Kbytes. Windows Installer does not automatically write this value.

Examples

Use the following example command line if the CD-ROM shipped to end users stores the application's installation package at the root of the CD-ROM. Note that the volume label in the Media Table of the .msi file must match the volume label of the CD-ROM.

Msiexec /I package.msi /qn /le logfile.txt ALLUSERS=1 FASTOEM=1 DISABLEROLLBACK=1

Use the following example command line if the installation package is not located at the root of the CD-ROM shipped to end users. You must set the MEDIAPACKAGEPATH property in this case to the path to the installation package. The volume label in the Media Table of the .msi file must match the volume label of the CD-ROM. In this case follow this example.

Msiexec /I package.msi /qn /le logfile.txt ALLUSERS=1 FASTOEM=1 DISABLEROLLBACK=1 MEDIAPACKAGEPATH=folder\package.msi


FavoritesFolder Property

The installer sets the FavoritesFolder property to the full path of the Favorites folder for the current user.

Remarks

Common values for this property are C:\Winnt\Profiles\[LogonUser]\Favorites\ (Windows NT/Windows 2000) and C:\Windows\Favorites\ (Windows 95 and Windows 98).


FILEADDDEFAULT Property

The value of the FILEADDDEFAULT property is a list of file keys delimited by commas that are installed in their default configuration. For each file key in the list, the installer determines the component that controls that file and installs the feature that requires the least disk space. The file keys in the list must be present in the File column of the File table. A feature is installed in the same installation state as if the user had requested an installation-on-demand of the feature. The state is determined by which bits are set for the feature in the Attributes column of the Feature table, and which bits are set for the feature's components in the Attributes column of the Component table.

Remarks

Note that the file key names are case-sensitive. Also note that if the SourceOnly bit flag is set in the Attributes column of the Component table for a component, then the component is installed to run from source.

The installer always evaluates the following properties in the following order.

  1. ADDLOCAL
  2. REMOVE
  3. ADDSOURCE
  4. ADDDEFAULT
  5. REINSTALL
  6. ADVERTISE
  7. COMPADDLOCAL
  8. COMPADDSOURCE
  9. FILEADDLOCAL
  10. FILEADDSOURCE
  11. FILEADDDEFAULT

For example, if the command line specifies: ADDLOCAL=ALL, ADDSOURCE = MyFeature, all the features are first set to run-local and then MyFeature is set to run-from-source. If the command line is: ADDSOURCE=ALL, ADDLOCAL=MyFeature, first MyFeature is set to run-local, and then when ADDSOURCE=ALL is evaluated, all features (including MyFeature) are reset to run-from-source.

The installer sets the Preselected property to a value of "1" during the resumption of a suspended install or when any of the above properties are specified on the command line.


FILEADDLOCAL Property

The value of the FILEADDLOCAL property value is a list of file keys delimited by commas that are to be installed to run locally. For each file key in the list, the installer determines the component that controls that file, then examines all features linked to that component by the FeatureComponents table and installs the feature that requires the least disk space. The file keys in the list must be present in the File column of the File table.

Remarks

Note that the file key names are case sensitive. Also note that if the SourceOnly bit flag is set in the Attributes column of the Component table for a component, then the component is installed to run from source.

The installer always evaluates the following properties in the following order.

  1. ADDLOCAL
  2. REMOVE
  3. ADDSOURCE
  4. ADDDEFAULT
  5. REINSTALL
  6. ADVERTISE
  7. COMPADDLOCAL
  8. COMPADDSOURCE
  9. FILEADDLOCAL
  10. FILEADDSOURCE
  11. FILEADDDEFAULT

For example, if the command line specifies: ADDLOCAL=ALL, ADDSOURCE = MyFeature, all the features are first set to run-local and then MyFeature is set to run-from-source. If the command line is: ADDSOURCE=ALL, ADDLOCAL=MyFeature, first MyFeature is set to run-local, and then when ADDSOURCE=ALL is evaluated, all features (including MyFeature) are reset to run-from-source.

The installer sets the Preselected property to a value of "1" during the resumption of a suspended install or when any of the above properties are specified on the command line.


FILEADDSOURCE Property

The value of the FILEADDSOURCE property denotes a list of file keys delimited by commas that are to be installed to run from the source media. For each file key in the list, the installer determines the component that controls that file, then examines all features linked to that component by the FeatureComponents table and installs the feature that requires the least amount of disk space. The file keys in the list must be present in the File column of the File table.

Remarks

Note that the file key names are case-sensitive. Also note that if the LocalOnly bit flag is set in the Attributes column of the Component table for a component, then the component is installed to run locally.

The installer always evaluates the following properties in the following order.

  1. ADDLOCAL
  2. REMOVE
  3. ADDSOURCE
  4. ADDDEFAULT
  5. REINSTALL
  6. ADVERTISE
  7. COMPADDLOCAL
  8. COMPADDSOURCE
  9. FILEADDLOCAL
  10. FILEADDSOURCE
  11. FILEADDDEFAULT

For example, if the command line specifies: ADDLOCAL=ALL, ADDSOURCE = MyFeature, all the features are first set to run-local and then MyFeature is set to run-from-source. If the command line is: ADDSOURCE=ALL, ADDLOCAL=MyFeature, first MyFeature is set to run-local, and then when ADDSOURCE=ALL is evaluated, all features (including MyFeature) are reset to run-from-source.

The installer sets the Preselected property to a value of "1" during the resumption of a suspended install or when any of the above properties are specified on the command line.


FontsFolder Property

The installer sets the FontsFolder property to the full path of the system Fonts folder.


Installed Property

The Installed property is set only if the product is installed per-machine or for the current user. This property is not set if the product is installed for a different user.

The Installed property can be used in conditional expressions to determine whether a product is installed per-computer or for the current user. For example, the property can be used in the conditional column of a sequence table or to differentiate between a first installation and a maintenance installation.

To determine whether the product is installed for a different user, check the ProductState property.


INSTALLLEVEL Property

The INSTALLLEVEL property is the initial level at which features are selected "ON" for installation by default. For any installation, there is a defined installation level specified by the INSTALLLEVEL property, which can be an integral from 1 to 32,767. For further discussion of installation levels, see Feature table.

Default Value

If no value is specified, the install level defaults to 1.

Remarks

The installation level specified by the INSTALLLEVEL property can be overridden by the following properties:

ADDLOCAL

ADDSOURCE

ADDDEFAULT

COMPADDLOCAL

COMPADDSOURCE

FILEADDLOCAL

FILEADDSOURCE

REMOVE

REINSTALL

ADVERTISE

For example, setting ADDLOCAL=All installs all features locally regardless of the value of the INSTALLLEVEL property. If the value of the Level column in the Feature table is 0, that feature is not installed and not displayed in the UI.

An administrator can permanently disable a feature by applying a customization transform that sets a 0 in the Level column for that feature. The application of the customization transform prevents the installation and display of the feature even if the user selects a complete installation using the UI or by setting ADDLOCAL to ALL on the command line. See A Customization Transform Example.

See Also

Feature table


Intel Property

The Intel property is defined only if running on an Intel processor. The value is set by the installer to the numeric processor level, for example 4 for 486, 5 for P5, 6 for P6, etc.


Intel64 Property

The Intel64 property is defined only if running on an IA-64 processor. The value is set by the installer to the numeric processor level. For more information, see also Intel Property.


IsAdminPackage Property

The installer sets the IsAdminPackage property to 1 if the current installation is running from a package created through an administrative installation.


LIMITUI Property

If the LIMITUI property is set, the UI level used when installing the package is restricted to Basic. This property is required in packages that have no authored UI but still contain UI tables such as the Dialog table. For a description of UI levels, see MsiSetInternalUI.

Remarks

Installation packages containing the LIMITUI property must also contain the ARPNOMODIFY property. This is required for a user to obtain the correct behavior from the Add/Remove Program control panel applet when attempting to configure a product.

See Also

MsiSetInternalUI, ARPNOMODIFY property


LeftUnit Property

If the LeftUnit property is set, the unit is placed to the left of the number instead of the typical right side. This accommodates languages where this is the accepted format. The UI uses this property to display the size of files and the available space on different volumes.


LocalAppDataFolder Property

Full path to the file system directory that serves as the data repository for local (non-roaming) applications. A common value for this property is C:\WINNT\Profiles\username\Local Settings\Application Data.

Remarks

This property is not available with Windows Installer version 1.0.


LOGACTION Property

The LOGACTION property is a list of action names separated only by semicolons and with no spaces. The action names in this property are case-insensitive and the list can end with a semicolon.

The installer logs Action Data messages for the actions that are in the list. The property has no effect on other types of logging.


LogonUser Property

The LogonUser property is the user name for the currently logged on user. Set by the installer by a system call to GetUserName.


Manufacturer Property

The Manufacturer property is the name of the manufacturer for the product. It is advertised as a product property.

This property is REQUIRED.


MEDIAPACKAGEPATH Property

If the installation package shipping with an application is not at the root of the CD-ROM that customers receive, the MEDIAPACKAGEPATH property must be set on the command line to the relative path of the application on the CD-ROM.

For example, if the path to the package on the media is E:\MyPath\My.msi, then use MEDIAPACKAGEPATH="\MyPath\".

Administrators may create CD-ROMs from an administrative installation point. If the location of the root of the installation is changed on the new CD-ROMs, the MEDIAPACKAGEPATH property must be set to the new path to install from this media. A source with a location on the CD-ROM different than what is specified in the package is unusable. It is not necessary, however, to use this property when creating an administrative installation point from shipping media.


MsiNTProductType Property

The installer sets this property for Windows NT, Windows 2000, and post Windows 2000 operating systems. This property indicates the Windows product type.

For operating systems earlier than Windows 2000 the installer sets the following values.

Value | Meaning
1 | Windows NT work station
2 | Windows NT domain controller
3 | Windows NT server

For Windows 2000 and later operating systems the installer sets this property to the value of the dwProductType field of the OSVERSIONINFOEX structure .

Value | Meaning
VER_NT_WORKSTATION | Windows 2000 Professional
VER_NT_DOMAIN_CONTROLLER | Windows 2000 domain controller
VER_NT_SERVER | Windows 2000 Server

Remarks

This property is only available with Windows Installer version 1.5 and later versions of the Windows installer.


MsiNTSuiteBackOffice Property

On Windows 2000 and later operating systems, the installer sets this property to 1 if Microsoft BackOffice components are installed. The installer sets this property to 1 if and only if the VER_SUITE_BACKOFFICE flag is set in the OSVERSIONINFOEX structure . Otherwise the installer does not set this property.

The installer does not set this property on operating systems earlier than Windows 2000.

Remarks

This property is only available with Windows Installer version 1.5 and later versions of the Windows installer.


MsiNTSuiteDataCenter Property

On Windows 2000 and later operating systems, the installer sets this property to 1 if Windows 2000 DataCenter Server is installed. The installer sets this property to 1 if and only if the VER_SUITE_DATACENTER flag is set in the OSVERSIONINFOEX structure . Otherwise the installer does not set this property.

The installer does not set this property on operating systems earlier than Windows 2000.

Remarks

This property is only available with Windows Installer version 1.5 and later versions of the Windows installer.


MsiNTSuiteEnterprise Property

On Windows 2000 and later operating systems, the installer sets this property to 1 if Windows® 2000 Advanced Server is installed. The installer sets this property to 1 if and only if the VER_SUITE_ENTERPRISE flag is set in the OSVERSIONINFOEX structure . Otherwise the installer does not set this property.

The installer does not set this property on operating systems earlier than Windows 2000.

Remarks

This property is only available with Windows Installer version 1.5 and later versions of the Windows installer.


MsiNTSuiteSmallBusiness Property

On Windows 2000 and later operating systems, the installer sets this property to 1 if Microsoft Small Business Server is installed. The installer sets this property to 1 if and only if the VER_SUITE_SMALLBUSINESS flag is set in the OSVERSIONINFOEX structure . Otherwise the installer does not set this property.

The installer does not set this property on operating systems earlier than Windows 2000.

Remarks

This property is only available with Windows Installer version 1.5 and later versions of the Windows installer.


MsiNTSuiteSmallBusinessRestricted Property

On Windows 2000 and later operating systems, the installer sets this property to 1 if Microsoft Small Business Server is installed with the restrictive client license in force. The installer sets this property to 1 if and only if the VER_SUITE_SMALLBUSINESS_RESTRICTED flag is set in the OSVERSIONINFOEX structure . Otherwise the installer does not set this property.

The installer does not set this property on operating systems earlier than Windows 2000.

Remarks

This property is only available with Windows Installer version 1.5 and later versions of the Windows installer.


MsiNTSuitePersonal Property

On Windows 2000 and later operating systems, the installer sets this property to 1 if the operating system is Workstation Personal. The installer sets this property to 1 if and only if the VER_SUITE_PERSONAL flag is set in the OSVERSIONINFOEX structure . Otherwise the installer does not set this property.

The installer does not set this property on operating systems earlier than Windows 2000.

Remarks

This property is only available with Windows Installer version 1.5 and later versions of the Windows installer.


MyPicturesFolder Property

Full path to the MyPictures folder. A common path is C:\WINNT\Profiles\username\My Documents\My Pictures.

Remarks

This property is not available with Windows Installer version 1.0.


OLEAdvtSupport Property

The installer sets the OLEAdvtSupport property to true when the current user's system has been upgraded to work with install-on-demand through COM. Note that for the installer to register a COM class and enable installation-on-demand, the class must be listed in the Class and ProgId tables.

See Also

ShellAdvtSupport Property, Platform Support of Advertisement


OutOfDiskSpace Property

The installer sets the OutOfDiskSpace property to TRUE if any volume that is a target of the current install has insufficient disk space to accommodate the installation. If all volumes have sufficient space, the value is FALSE. Selection resolution actions use this value to cancel an installation and generate a dialog box.

This property is valid at any time after the CostFinalize action is executed. The OutOfNoRbDiskSpace property status is dynamically updated any time the total install cost is recalculated (for example, any time the install state of any feature is changed via the Selection dialog).

Remarks

Any dialog relying on the OutOfDiskSpace property to determine whether to bring up a dialog must set the TrackDiskSpace Dialog Style Bit for the dialog to dynamically update space on the target volumes.


OutOfNoRbDiskSpace Property

The installer sets the OutOfNoRbDiskSpace property to True if any volume that is a target of the installation has insufficient disk space to accommodate the installation. In this case, the OutOfNoRbDiskSpace property is set to True even if rollback has been disabled. If all volumes have sufficient space, the value is False.

A developer of an installation package can handle the situation when the OutOfDiskSpace property is True and the OutOfNoRbDiskSpace property is False by authoring a user interface that presents the user with an option to disable rollback and continue the installation. For information about conditionally displaying a dialog box, see ControlEvent Overview. For information about disabling rollback, see EnableRollback ControlEvent.

The OutOfNoRbDiskSpace property is valid at any time after the CostFinalize action has been executed. The OutOfNoRbDiskSpace property status is dynamically updated any time the total install cost is recalculated (for example, any time the install state of any feature is changed via the Selection dialog). Selection resolution actions use this value to cancel an installation and generate a dialog box.

See Also

ControlEvent Overview, OutOfDiskSpace property, EnableRollback ControlEvent, CostFinalize action, Selection dialog


PATCH Property

The PATCH property is the full path of the current patch package.

The PATCH property is set by MsiApplyPatch or by using the /p Command Line Option. The PATCH property is set only during the first application of the patch. The patch is applied for each subsequent configuration of the product, but the PATCH property is not set.

Remarks

The PATCH property can be used in conditional expressions to control an action or user interface that is run only during the first application of the patch.


PATCHNEWPACKAGECODE Property

The PATCHNEWPACKAGECODE property updates the Revision Number Summary property of an administrative image during patching. This property is only set by a transform in a .msp file. The .msp file must include a transform that adds this property to the Property table and sets its value. The installer then writes the value of PATCHNEWPACKAGECODE to the Revision Number Summary property.

Remarks

The PATCHNEWPACKAGECODE, PATCHNEWSUMMARYCOMMENTS, and PATCHNEWSUMMARYSUBJECT properties are used to update the summary information when a patch is installed to an administrative image.


PATCHNEWSUMMARYCOMMENTS Property

The PATCHNEWSUMMARYCOMMENTS property updates the Comments Summary property of an administrative installation during patching. This property is only set by a transform in a .msp file. The .msp file must include a transform that adds this property to the Property table and sets its value. The installer then writes the value of PATCHNEWSUMMARYCOMMENTS to the Revision Number Summary property.

Remarks

The PATCHNEWPACKAGECODE, PATCHNEWSUMMARYCOMMENTS, and PATCHNEWSUMMARYSUBJECT properties are used to update the summary information when a patch is installed to an administrative image.


PATCHNEWSUMMARYSUBJECT Property

The PATCHNEWSUMMARYSUBJECT property updates the Subject Summary property of an administrative image during patching. This property is only set by a transform in a .msp file. The .msp file must include a transform that adds this property to the Property table and sets its value. The installer then writes the value of PATCHNEWSUMMARYSUBJECT to the Revision Number Summary property.

Remarks

The PATCHNEWPACKAGECODE, PATCHNEWSUMMARYCOMMENTS, and PATCHNEWSUMMARYSUBJECT properties are used to update the summary information when a patch is installed to an administrative image.


PersonalFolder Property

The installer sets the PersonalFolder property to the full path to the Personal folder for the current user.

Remarks

Common values for this property are C:\Winnt\Profiles\[LogonUser]\Personal\ (Windows NT/Windows 2000) and C:\My Documents\ (Windows 95 and Windows 98).


PhysicalMemory Property

The installer sets the PhysicalMemory property to the size of the installed RAM in megabytes.


PIDTemplate Property

The PIDTemplate property contains the string used as a template for the PIDKEY property. For the syntax used in the template, see the MaskedEdit control type. ValidateProductID Action uses this value to validate the Product ID.


Preselected Property

The Preselected property indicates that features have already been selected and that the selection dialog need not be shown.

Conditional expressions which depend on whether features are already installed use this value. For example, the property can be used to suppress any dialogs involving feature selections during the resumption of a suspended installation.

The installer sets the Preselected property to a value of "1" during the resumption of a suspended install or when any of the following properties are specified on the command line. The installer always evaluates these properties in the following order.

  1. ADDLOCAL
  2. REMOVE
  3. ADDSOURCE
  4. ADDDEFAULT
  5. REINSTALL
  6. ADVERTISE
  7. COMPADDLOCAL
  8. COMPADDSOURCE
  9. FILEADDLOCAL
  10. FILEADDSOURCE
  11. FILEADDDEFAULT


Privileged Property

The Privileged property indicates whether the installation is performed in the context of elevated privileges. The installer sets this property if the user has administrator privileges, if the application has been assigned by a system administrator, or if both the user and machine policies AlwaysInstallElevated are set to true.

Default Value

The installer does not set this property if the user is not allowed to install with elevated privileges.

Remarks

Developers of installer packages can use the Privileged property to make the installation conditional upon system policy, the user being an administrator, or assignment by an administrator.


ProductCode Property

The ProductCode property is a unique identifier for the particular product release, represented as a string GUID, for example "{12345678-1234-1234-1234-123456789012}". Letters used in this GUID must be uppercase. This ID must vary for different versions and languages.

A product upgrade that updates a product into an entirely new product must also change the product code. The 32-bit and 64-bit versions of an application's package must be assigned different product codes.

The ProductCode is advertised as a product property, and is the primary method of specifying the product. This property is REQUIRED.

See Also

Product Codes


ProductID Property

The ProductID property is set to the full Product ID after a successful validation. If the installer package does not use a Product ID, then the ProductID property must be set to "none" in the Property table.

This value is displayed by the UI and used by the RegisterProduct action.

Following a successful validation, this property is set by the ValidateProductID action or the ValidateProductID ControlEvent.


PIDKEY Property

The PIDKEY property contains the part of the Product ID entered by the user. The ValidateProductID action validates the Product ID entered by comparing the PIDKEY property to the PIDTemplate property.

The PIDKEY property can be set on the command line or through the user interface. This property contains only the part of the Product ID that is entered by the user.


PRIMARYFOLDER Property

The PRIMARYFOLDER is a global property that allows the author to designate a primary folder for the installation. The value for this property must be the key name of a directory that exists in the Directory table.

The installer uses the resolved path of the primary folder to determine which volume to use when setting the values of the PrimaryVolumePath property, PrimaryVolumeSpaceAvailable property, PrimaryVolumeSpaceRequired property, and PrimaryVolumeSpaceRemaining property. The installer may provide the values of these latter properties to users in the user interface to help them manage disk space. Commonly package authors can select the largest folder as the primary folder.

The value for this property must be the key name of a directory record found in the Directory table.


PrimaryVolumePath Property

The installer sets the value of the PrimaryVolumePath property to the path of the volume designated by the PRIMARYFOLDER property. For example, if the folder referenced by PRIMARYFOLDER resolves to "D:\ProgramFiles", PrimaryVolumePath is set to "D:"


PrimaryVolumeSpaceAvailable Property

The installer sets the value of the PrimaryVolumeSpaceAvailable property to a string representing the total number of bytes available, in units of 512, on the volume referenced by the PrimaryVolumePath property.

Remarks

For example, if PrimaryVolumePath is set to "D:", and volume D: has 446,134,272 bytes free, PrimaryVolumeSpaceAvailable is set to 871356.

Note if this value is to be displayed within a static Text control, the FormatSize bit can be used to automatically format and label this number in units of kilobytes or megabytes as appropriate.


PrimaryVolumeSpaceRequired Property

The installer sets the value of the PrimaryVolumeSpaceRequired property to a string representing the total number of bytes required by all selected features on the volume referenced by the PrimaryVolumePath property. As with the PrimaryVolumeSpaceAvailable property, this number is expressed in units of 512 bytes.

Remarks

Note if this value is to be displayed within a static Text control, the FormatSize bit can be used to automatically format and label this number in units of kilobytes or megabytes as appropriate.


PrimaryVolumeSpaceRemaining Property

The installer sets the value of the PrimaryVolumeSpaceRemaining property to a string representing the total number of bytes remaining on the volume referenced by the PrimaryVolumePath property, if all currently selected features were installed. As with the PrimaryVolumeSpaceAvailable property, this number is expressed in units of 512 bytes.

Remarks

Note if this value is to be displayed within a static Text control, the FormatSize bit can be used to automatically format and label this number in units of kilobytes or megabytes as appropriate.


ProductLanguage Property

The ProductLanguage property specifies the language the installer should use for any strings in the user interface that are not authored into the database. This property must be a numeric language identifier (LANGID). If a transform changes the language of the user interface in the database, then it should also change the value of this property to reflect the new language.

This property is REQUIRED.

Remarks

The value of the ProductLanguage property must be one of the languages listed in the Template Summary Property.


ProductName Property

The ProductName property contains the name of the application being installed, for example, Microsoft® Office 97. This is only used for display purposes. Advertised as a product property.

This property is REQUIRED.

This property can be changed by a transform.


ProductState Property

The installer sets the ProductState property to the installation state for the product at initialization. This property is set to one of the following INSTALLSTATE data types returned by MsiQueryProductState.

INSTALLSTATE | Numeric value | Installation state of product
INSTALLSTATE_UNKNOWN | -1 | The product is neither advertised or installed.
INSTALLSTATE_ADVERTISED | 1 | The product is advertised but not installed.
INSTALLSTATE_ABSENT | 2 | The product is installed for a different user.
INSTALLSTATE_DEFAULT | 5 | The product is installed for the current user.


ProductVersion Property

The value of the ProductVersion property is the version of the product in string format. This property is REQUIRED.

The format of the string is as follows:

major.minor.build

The first field is the major version and has a maximum value of 255. The second field is the minor version and has a maximum value of 255. The third field is called the build version or the update version and has a maximum value of 65,535.

Remarks

At least one of the three fields of ProductVersion must change for an upgrade using the Upgrade table. Any update that changes only the package code, but leaves ProductVersion and ProductCode unchanged is called a small update. The three versions fields are provided primarily for convenience. For example, if you want to change ProductVersion, but don't want to change either the major or minor versions, you can change the build version.

Note that Windows Installer uses only the first three fields of the product version. If you include a fourth field in your product version, the installer ignores the fourth field.

See Also

Patching and Upgrades, small update


ProgramFilesFolder Property

The installer sets ProgramFilesFolder property to the full path to the Program Files folder.

Remarks

The installer sets this property. For example, on 32-bit Windows the value may be C:\Program Files. When using 64-bit Windows, the value may be C:\Program Files (x86).


ProgramFiles64Folder Property

The installer sets the ProgramFiles64Folder property to the full path of the predefined 64-bit Program Files folder. The existing ProgramFilesFolder Property is set to the corresponding 32-bit folder.

Remarks

The installer sets this property. For example, on 64-bit Windows, the value may be C:\Program Files. This property is not used on 32-bit Windows.


ProgramMenuFolder Property

The installer sets the ProgramMenuFolder property to the full path to the Program Menu folder for the current user. If an "All Users" profile exists and the ALLUSERS property is set, then this property is set to the folder in the "All Users" profile.

Remarks

Common values for this property are C:\Winnt\Profiles\[LogonUser]\Start Menu\Programs\ (Windows NT/Windows 2000) and C:\Windows\Start Menu\Programs\ (Windows 95 and Windows 98).


PROMPTROLLBACKCOST Property

The PROMPTROLLBACKCOST property specifies the action the installer takes if rollback installation capabilities are enabled and there is insufficient disk space to complete the installation.

The possible values of PROMPTROLLBACKCOST are as follows.

Value | Action
P | Display a dialog box asking whether to continue without a rollback.
D | Disable rollback and continue without asking user.
F | Fail with the out-of-disk-space error prompt.

Remarks

When the user interface is run at the Basic or no UI level, the installer handles all the out-of-disk-space logic automatically.

When the user interface runs at the Full level, the user can be given additional options, such as prompting before proceeding with a rollback, disabling rollback, or proceeding without rollback when the disk is full. It is up to the package developer to author the dialog box sequence to provide the appropriate choices to the user. The elements available to do this are the EnableRollback ControlEvent, OutOfDiskSpace property, OutOfNoRbDiskSpace property, and the PROMPTROLLBACKCOST property.


REBOOT Property

The REBOOT property suppresses certain prompts for a reboot of the system. An administrator typically uses this property with a series of installations to install several products at the same time with only one reboot at the end. For more information, see System Reboots.

The ForceReboot and ScheduleReboot action actions inform the installer to prompt the user to reboot the system. The installer can also determine that a reboot is necessary whether there are any ForceReboot or ScheduleReboot actions in the sequence. For example, the installer automatically prompts for a reboot if it needs to replace any files in use during the installation.

You can suppress certain prompts for reboots by setting the REBOOT property as follows.

REBOOT value | Description
Force | Always prompt for a reboot at the end of the installation. The UI always prompts the user with an option to reboot at the end. If there is no user interface the system automatically reboots at the end of the installation.
Suppress | Suppress prompts for a reboot at the end of the installation. The installer still prompts the user with an option to reboot during the installation whenever it encounters the ForceReboot action. If there is no user interface, the system automatically reboots at each ForceReboot. Reboots at the end of the installation, for example caused by an attempt to install a file in use, are suppressed.
ReallySuppress | Suppress all prompts for reboots during the installation initiated by ForceReboot and all prompts at end of the installation.

Remarks

The installer only evaluates the first character of the REBOOT property.

See Also

REBOOTPROMPT Property, System Reboots


REBOOTPROMPT Property

If the REBOOTPROMPT property is set to Suppress (or just S) any reboot performed by the Windows Installer happens automatically without interaction from the user. Setting this property does not initiate a reboot if one is not needed, it only suppresses the display of any prompts for reboots to the user.

See Also

System Reboots, REBOOT Property


RedirectedDLLSupport Property

The installer sets the RedirectedDLLSupport property if the system platform performing the installation supports Isolated Components. The installer sets the property for Windows 98 SE and Windows 2000 and later system versions.

The RedirectedDLLSupport property may be used to condition the IsolateComponents action in the InstallUISequence table or InstallExecuteSequence table.

This property is only available in Windows Installer version 1.1 and later versions.

See Also

Using Properties in Conditional Statements


REINSTALL Property

The value of the REINSTALL property is a list of features delimited by commas that are to be reinstalled. The features listed must be present in the Feature column of the Feature table. To reinstall all features use REINSTALL=All on the command line.

Remarks

Note that the feature names are case-sensitive.

If the REINSTALL property is set, the REINSTALLMODE property should also be set, to indicate the type of reinstall to be performed. If the REINSTALLMODE property is not set, then by default all files that are currently installed are reinstalled, IF the currently installed file is a lesser version (or is not present). By default, no registry entries are rewritten.

Note that even if REINSTALL is set to "ALL", only those features that were already installed previously are reinstalled. Thus, if REINSTALL is set for a product that is yet to be installed, no installation action will take place at all.

The installer always evaluates the following properties in the following order:

  1. ADDLOCAL
  2. REMOVE
  3. ADDSOURCE
  4. ADDDEFAULT
  5. REINSTALL
  6. ADVERTISE
  7. COMPADDLOCAL
  8. COMPADDSOURCE
  9. FILEADDLOCAL
  10. FILEADDSOURCE
  11. FILEADDDEFAULT

For example, if the command line specifies: ADDLOCAL=ALL, ADDSOURCE = MyFeature, all the features are first set to run-local and then MyFeature is set to run-from-source. If the command line is: ADDSOURCE=ALL, ADDLOCAL=MyFeature, first MyFeature is set to run-local, and then when ADDSOURCE=ALL is evaluated, all features (including MyFeature) are reset to run-from-source.

The installer sets the Preselected property to a value of "1" during the resumption of a suspended install or when any of the above properties are specified on the command line.


REINSTALLMODE Property

The REINSTALLMODE property is a string containing letters specifying the type of reinstall to perform. Options are case-insensitive and order-independent. This property should normally always be used in conjunction with the REINSTALL property. However, this property can also be used during install, not just reinstall.

Default Value

By default the REINSTALLMODE is "omus".

Reinstall Option Codes

Code | Option
p | Reinstall only if file is missing (i.e., verify that the file is present).
o | Reinstall if file is missing, or an older version is present.
e | Reinstall if file is missing, or an equal or older version is present
d | Reinstall if file is missing, or a different version is present
c | Reinstall if file is missing, or corrupt. This option only repairs files that have msidbFileAttributesChecksum in the Attributes column of the File table.
a | Force all files to be reinstalled, regardless of checksum or version.
u | Rewrite all required registry entries from the Registry table that go to the HKEY_CURRENT_USER or HKEY_USERS registry hive.
m | Rewrite all required registry entries from the Registry table that go to the HKEY_LOCAL_MACHINE or HKEY_CLASSES_ROOT registry hive. Rewrite all information from the Class table, Verb table, PublishComponent table, ProgID table, MIME table, Icon table, Extension table, and AppID table regardless of machine or user assignment. Reinstall all qualified components.
s | Reinstall all shortcuts and re-cache all icons overwriting any existing shortcuts and icons.
v | Use to run from the source package and re-cache the local package.

If the REINSTALLMODE property is defined without the REINSTALL property defined, then the specified "detection" modes still apply; however, only those features that are selected normally for install are actually "reinstalled". Thus, in this case, REINSTALLMODE actually specifies the "overwrite" mode for a normal install.

The option codes for this property correspond to the command line option '/f'. The command line option has a default value of 'pecms'.

Note Only those files containing checksum information are ever verified and repaired. The REINSTALLMODE_FILEVERIFY flag (c option above) only repairs files that have msidbFileAttributesChecksum in the Attributes column of the File table.


RemoteAdminTS Property

The installer sets this property when the system is configured for Remote Administration using Windows Terminal Services. Note that in this case the installer does not set the TerminalServer property.

Note that this property is not available with Windows Installer version 1.0.

Default Value

None. The property is undefined when not running on a remote administration server with Terminal Services.

Remarks

The RemoteAdminTS property can only be set on Microsoft Windows® 2000 or later. The TerminalServer property can be set on Microsoft® Windows® 2000 or Windows NT® 4.0.


REMOVE Property

The value of the REMOVE property is a list of features delimited by commas that are to be removed. The features must be present in the Feature column of the Feature table. To remove all features (for example, uninstall the entire product), use REMOVE="Al" on the command line.

Remarks

To determine whether a product has been set to be completely uninstalled, a package author may use a conditional expression to check whether REMOVE="ALL". Note that if the product is removed by setting its top feature to absent, the REMOVE property may not equal "ALL" until after the InstallValidate action. This means that any custom action that depends upon REMOVE="ALL" must be sequenced after the InstallValidate. For more information see also Conditioning Actions to Run During Removal. Note that the feature names are case-sensitive.

The installer always evaluates the following properties in the following order:

  1. ADDLOCAL
  2. REMOVE
  3. ADDSOURCE
  4. ADDDEFAULT
  5. REINSTALL
  6. ADVERTISE
  7. COMPADDLOCAL
  8. COMPADDSOURCE
  9. FILEADDLOCAL
  10. FILEADDSOURCE
  11. FILEADDDEFAULT

For example, if the command line specifies ADDLOCAL=ALL, ADDSOURCE = MyFeature, all the features are first set to run-local and then MyFeature is set to run-from-source. If the command line is ADDSOURCE=ALL, ADDLOCAL=MyFeature, first MyFeature is set to run-local, then when ADDSOURCE=ALL is evaluated, all features (including MyFeature) are reset to run-from-source.

The installer sets the Preselected property to a value of "1" during the resumption of a suspended install or when any of the above properties are specified on the command line.


ReplacedInUseFiles Property

The ReplacedInUseFiles property is set if the installer writes over a file that is being held in use. This property is used by custom actions to detect that a reboot is required to complete the installation.

Set during the InstallExecute and InstallFinalize actions.

See Also

System Reboots


RestrictedUserControl Property

The RestrictedUserControl property should be set to 1 if restricting which public properties can be sent to the server side. Authors can use this property in conditional statement to make the execution of dialogs or actions depend upon whether there are restrictions on public properties.

See Also

Restricted Public Properties


RESUME Property

The RESUME property is set when resuming a suspended install. This property can determine what text to display in the UI. For example, when not in resume mode the user could be asked "Are you ready to install?" while in resume mode the user could be asked "Are you ready to complete your install?".

Remarks

For backward-compatibility, the installer also supports the name Resume for this property.


ROOTDRIVE Property

The ROOTDRIVE property specifies the default drive for the destination directory of the installation. If the Directory column of the Directory table indicates the root destination directory by a property name that is undefined, the installer uses the value of the ROOTDRIVE property to resolve the path to the destination directory.

If ROOTDRIVE is not set at a command line or authored into the Property table, the installer sets this property. During an administrative installation the installer sets ROOTDRIVE to the first connected network drive it finds that can be written to. If it is not an administrative installation, or if the installer can find no network drives, the installer sets ROOTDRIVE to the local drive that can be written to having the most free space.

The value for this property must end with '\'.


ScreenX Property

The installer sets the ScreenX property to the width of the screen in pixels.


ScreenY Property

The installer sets the ScreenY property to the height of the screen in pixels.


SecureCustomProperties Property

The SecureCustomProperties is a list of public properties delimited by semi-colons. These properties are included with the default list of restricted public properties that the installer can pass to the server side when doing a managed installation with elevated privileges.

See Also

Restricted Public Properties


SendToFolder Property

The installer sets the SendToFolder property to the full path to the SendTo folder for the current user.

Remarks

Common values for this property are C:\Winnt\Profiles\[LogonUser]\SendTo\ (Windows NT/Windows 2000) and C:\Windows\SendTo\ (Windows 95 and Windows 98).


SEQUENCE Property

The SEQUENCE property specifies a table having the same schema as the InstallExecuteSequence table, that is Action, Condition, and Sequence columns. This property is used by the SEQUENCE action.

Remarks

The SEQUENCE action will run the actions in the table in the order specified by the Sequence column of the table.


ServicePackLevel Property

The installer sets the ServicePackLevel property to the numerical value of the operating system service pack level, if one is installed. For example, if Windows NT Service Pack Level 3 is installed, the installer sets the value of this property to 3.

The minor revision number, if there is one, is held by the ServicePackLevelMinor property.

See also Operating System Property Values.


ServicePackLevelMinor Property

This property is used in conjunction with the ServicePackLevel property. It holds the minor revision number of the service pack installed on the machine.

This property is set only on Windows 2000.

This property is not available with Windows Installer version 1.0.


SharedWindows Property

The installer sets the SharedWindows property when the system is operating as Shared Windows.


ShellAdvtSupport Property

The ShellAdvtSupport property is set by the installer if the system's IShellLink interface supports installer descriptor resolution.

Remarks

If this property is set, the system's IShellLink interface supports installer descriptor resolution. This is supported by Microsoft® Windows® 2000, Microsoft® Windows® 98, and systems running Microsoft® Internet Explorer 4.01. If this property is not set, the installer has the default behavior of creating non-advertised features during installation, either locally or run from source.

See Also

Platform Support of Advertisement


SHORTFILENAMES Property

Setting the SHORTFILENAMES property causes short file names to be used for the names of target files, rather than long file names. It does not affect the file names the installer looks for at the source.

If the SHORTFILENAMES property is set during an administrative installation, the property may need to be set again by a user subsequently applying a patch to the administrative image. When using Windows Installer version 1.5 or later versions to apply the patch, the installer automatically sets the SHORTFILENAMES property if the administrative image uses short file names. With Windows Installer versions earlier than version 1.5, the user applying the patch must set the SHORTFILENAMES property.

Default Value

Long names are used by the installer if the SHORTFILENAMES property is not set and the target volume supports long names. Short names are used by the installer if the target volume does not support long names.

Remarks

When the SHORTFILENAMES property is set, the installer creates folders and installs files using short file names from any short|long pairs listed in the File table or Directory table.


SourceDir Property

The SourceDir property is the root directory containing the source cabinet file or the source file tree of the installation package. This value is used for directory resolution.

Default Value

The directory containing the installation package.

Remarks

The ResolveSource action must be called before using the SourceDir property in any expression or attempting to retrieve the value of SourceDir with MsiGetProperty. The ResolveSource action should not be run while the source is unavailable, such as when uninstalling an application, because this can cause an unintended prompt for the source media.


SOURCELIST Property

The SOURCELIST property is a semicolon-delimited list of network or URL source paths to the application's installation package. This list is appended to the end of each user's existing source list for the application. The installer locates a source by enumerating the list of source paths and uses the first accessible location it finds. Only this source can be used for the remainder of the installation. Each path specified in the source list must therefore be to a location having a complete source for the application. The entire directory tree at each source location must be the same and must include all of the required source files, including any cabinets. Each location must have an .msi file with the same file name and product code.

Default Value

The installer only checks the SOURCELIST property if the product has not already been advertised or installed. In all other cases the installer uses the existing source list that is in the registry.

Remarks

Sources added using the SOURCELIST property are added directly to the end of the list for each type of source and always come after the default source specified by the SourceDir property.

For Windows Installer versions earlier than version 1.5, the SOURCELIST property is limited to a maximum of 26 network sources plus 26 URL sources. For Windows Installer version 1.5 and later, the number of sources in the SOURCELIST property is unlimited. For Windows Installer version 1.1 and later MsiSourceListAddSource is used to add network sources beyond the limit of 26.

See Also

Source Resiliency


StartMenuFolder Property

The installer sets the StartMenuFolder property to the full path to the Start Menu folder. By default, this property is set to the folder for the current user. If an "All Users" profile exists and the ALLUSERS property is set, then this property is set to the folder in the "All Users" profile.

Remarks

Common values for this property are C:\Winnt\Profiles\[LogonUser]\Start Menu\ (Windows NT/Windows 2000) and C:\Windows\Start Menu\ (Windows 95 and Windows 98).


StartupFolder Property

The installer sets the StartupFolder property to the full path to the Startup folder. By default, this property is set to the folder for the current user. If an "All Users" profile exists and the ALLUSERS property is set, than this property is set to the folder in the "All Users" profile.

Remarks

Common values for this property are C:\Winnt\Profiles\[LogonUser]\Start Menu\Programs\Startup\ (Windows NT/Windows 2000) and C:\Windows\Start Menu\Programs\Startup\ (Windows 95 and Windows 98).


System16Folder Property

Windows Installer sets the System16Folder property to the full path to folder for 16-bit system DLLs. Note that the System16Folder property is not defined for 64-bit Windows because this system does not support 16-bit applications or components.

Remarks

Common values for this property are C:\Winnt\System\ (Windows NT/Windows 2000) and C:\Windows\System\ (Windows 95 and Windows 98).


SystemFolder Property

The installer sets the SystemFolder property to the full path of the System folder.

Remarks

The installer sets this property. For example, on 32-bit Windows the value may be C:\Windows\System32. On 64-bit Windows, the value may be C:\Windows\SysWow64.

This folder is normally a subdirectory of the Windows folder. However, it resides on a server when configured for Shared Windows.


System64Folder Property

The installer sets the System64Folder property to the full path to the predefined System64 folder. The existing SystemFolder property is set to the corresponding 32-bit folder.

Remarks

The installer sets this property on 64-bit Windows. For example, on 64-bit Windows, the value may be C:\Window\System32. This property is not used on 32-bit Windows.

This folder is normally a subdirectory of the Windows folder. However, it resides on a server when configured for Shared Windows.


SystemLanguageID Property

The SystemLanguageID property is the default language identifier for the system. The installer sets it by a call to GetSystemDefaultLangID.


TerminalServer Property

The installer sets the TerminalServer property when the system is a server with Terminal Services.

Default Value

None. The property is undefined when not running on Terminal Services.

Remarks

The RemoteAdminTS property can only be set on Microsoft Windows® 2000 or later. The TerminalServer property can be set on Windows 2000 or Windows NT 4.0.

See Also

RemoteAdminTS property


TARGETDIR Property

The TARGETDIR property specifies the root destination directory for the installation. TARGETDIR must be the name of one root in the Directory table. There may be only a single root destination directory. During an administrative installation this property is used as the location to copy the installation package

To specify the root destination directory, set the Directory column of the Directory table to the TARGETDIR property and the DefaultDir column to the SourceDir property. If the TARGETDIR property is defined, the destination directory is resolved to the property's value. If the TARGETDIR property is undefined, the ROOTDRIVE property is used to resolve the path. For more information about using the TARGETDIR property see Using the Directory Table.

Note that the value of the TARGETDIR property is typically set at the command line or through a user interface. Setting TARGETDIR by authoring a path into the Property table is not recommended because computers differ in the setup of the local drive.


TempFolder Property

The installer sets the TempFolder property to the full path to the Temp folder.

Remarks

A common value for this property is C:\Temp.


TemplateFolder Property

The installer sets the TemplateFolder property to the full path to the Template folder for the current user. Common values for this property are C:\Winnt\Profiles\[LogonUser]\ShellNew\ (Windows NT/Windows 2000) and C:\Windows\ShellNew\ (Windows 95 and Windows 98).

On Windows2000 only, if the ALLUSERS property is set, this property points to a file system directory that contains the templates that are available to all users. A common path is C:\WINNT\Profiles\All Users\Templates.


TextHeight Property

The installer sets the TextHeight property to the height (ascent + descent) of characters in logical units.


Time Property

The Time property is the current time in hours, minutes, and seconds as a string of literal text in the format HH:MM:SS.

Remarks

Because this is a text string, it cannot be used in conditional expressions.


TRANSFORMS Property

The TRANSFORMS property is a list of the transforms that the installer applies when installing the package. The installer applies the transforms in the same order as they are listed in the property. Transforms can be specified by their filename or full path. To specify multiple transforms, separate each file name or full path with a semicolon (;). For example, to apply three transforms to a package, set TRANSFORMS to a list of file names or to a list of full paths.

TRANSFORMS=transform1.mst;transform2.mst;transform3.mst
TRANSFORMS=\\server\share\path\transform1.mst;\\server2\share2\path2\transform2.mst;\\server3\share3\path3\transform3.mst

You can indicate that a transform file is embedded in a storage of the .msi file, rather than as a stand-alone file, by prefixing the filename with a colon (:). For example, the following example indicates that transform1.mst and transform2.mst are embedded inside the .msi file and that transform3.mst is a stand-alone file.

TRANSFORMS=:transform1.mst;:transform2.mst;transform3.mst

The installer requires the transforms listed in TRANSFORMS at every installation, advertisement, installation-on-demand, or maintenance installation of the package. The TransformsSecure policy, the TRANSFORMS property, and the first character of the TRANSFORMS string informs the installer how to handle the source resiliency of stand-alone transform files. Windows Installer version 1.1 treats setting TransformsAtSource or TRANSFORMSATSOURCE the same as TransformsSecure and TRANSFORMSSECURE. Note that transforms embedded in the .msi file are not cached and are always obtained from the package.

TRANSFORMS Property Transforms Secure Caching and Resiliency
@[list of filenames]

Example:

@transform1.mst;transform2.mst; transform3.mst

 No effect. Secure-At-Source transforms. The source of the transforms must be at the root of the source for the package. When the package is installed or advertised, the installer saves the transforms on the user's computer in a cache where the user does not have write access. If the local copy of the transform becomes unavailable, the installer searches for a source to restore the cache. The method is the same as searching the source list for an .msi file. See Source Resiliency.
|[list of paths]

Example:

|\\server\share\path\transform1.mst;\\server2\share2\path2\transform2.mst
 No effect. Secure-Full-Path transforms. The source of each transform must be at the full path passed to TRANSFORMS. The transform source does not have to be located at the source of the package. When the package is installed or advertised, the installer saves the transforms on the user's computer in a cache where the user does not have write access. If the local copy of the transform becomes unavailable the installer can only restore the cache from the source at the specified path.
[list of filenames]

The first character is not @ or |.

Example:

transform1.mst;transform2.mst; transform3.mst

 TransformsSecure or TRANSFORMSSECURE set to 1

OR

TransformsAtSource or TRANSFORMSATSOURCE set to 1.

 If TRANSFORMS is a list of filenames, the installer treats them as Secure-At-Source transforms.

If TRANSFORMS is a list of full paths, the installer treats them as Secure-Full-Path transforms.
[list of filenames]

The first character is not @ or |.

Example:

transform1.mst;transform2.mst; transform3.mst

 TransformsSecure and TRANSFORMSSECURE are not set

AND

TransformsAtSource and TRANSFORMSATSOURCE are not set.

 The source of the transforms must be at the root of the source for the package. When the package is installed or advertised, the installer saves the transforms in the user's profile. This enables a user to roam between computers while maintaining their customizations. If the local copy of the transform becomes unavailable the installer searches for a source to restore the cache. The method is the same as searching the source list for an .msi file. See Source Resiliency.
[list of paths]

The first character is not @ or |.

Example:

\\server\share\path\transform1.mst;\\server2\share2\path2\transform2.mst.
 TransformsSecure and TRANSFORMSSECURE are not set

AND

TransformsAtSource and TRANSFORMSATSOURCE are not set..

 Unsecured transforms. When the package is installed or advertised, the installer saves the transforms in an unsecured location where the user has write access. If the local copy of the transform becomes unavailable the installer may only restore the transform from the source at the path passed to TRANSFORMS.

You cannot use filenames and paths together in the same TRANSFORMS list. You cannot specify secure and profile transforms together in the same list. You may include transforms embedded in the package in a list with other transforms.

@transform1.mst;:transform2.mst
|\\server\share\path\transform1.mst;:transform2.mst

Note that because the list delimiter for transforms is the semicolon character, semicolons must not be used in a transform filename or path.

Remarks

In cases where the TransformsSecure policy or the TRANSFORMSSECURE property has been set with Windows Installer version 1.1, it is not necessary to pass the @ or | symbol when setting TRANSFORMS using the command line. The installer assumes Secure-At-Source or Secure-Full-Path if the list consists entirely of file names located at the source or consists entirely of full paths. You still cannot mix the two types of transform sources.

Note that the installer uses a different search order for unsecured transforms applied during first time and maintenance installations. For more information see Unsecured Transforms.

See Also

Transforms, Source Resiliency


TRANSFORMSATSOURCE Property

When using Windows Installer version 1.0, setting the TRANSPORMSATSOURCE property to 1 informs the installer that the location of transforms is at the root of the source of the installation package. If this property is set for a transform, the installer prefixes the @ symbol to that transform's filename in the transform list. The transform list is the value of the TRANSFORMS property. The installer then locates that transform, and all subsequent transforms in the list, at the root of the source where the .msi file is located.

Setting this property is like setting the TransformsAtSource policy except that the scope is different. Setting TransformsAtSource policy applies to all packages installed by a given user. Setting the TRANSFORMSATSOURCE property applies to the package regardless of the users.

Remarks

This property and policy are not available with Windows Installer version 1.1. Windows Installer version 1.1 interprets the TRANSFORMSATSOURCE property as though it were the TRANSFORMSSECURE property. If the @ flag is passed in the TRANSFORMS property, Windows Installer version 1.1 treats the transforms in the list as secure-at-source transforms.

See Also

Transforms


TRANSFORMSSECURE Property

Setting the TRANSFORMSECURE property to 1 informs the installer that transforms are to be cached locally on the user's computer in a location where the user does not have write access. Setting this property is like setting the TransformsSecure policy except that the scope is different. Setting TransformsSecure policy applies to all packages installed by a given user. Setting the TRANSFORMSSECURE property applies to the package regardless of the user.

The purpose of this property is to provide for secure transform storage with traveling users of Windows 2000. When this property is set, a maintenance installation can only use the transform from the specified path. If the path is not available the maintenance installation fails. A source for each secure transform must therefore reside at the location of the source of the installation package. Then if the installer finds that the transform is missing on the local computer, it can restore the transform from this source.

Remarks

The TRANSFORMSSECURE property is not available with Windows Installer version 1.0.

Windows Installer version 1.1 interprets the TRANSFORMSATSOURCE property to be the same as the TRANSFORMSSECURE property.

See Also

Transforms


TTCSupport Property

The installer sets the TTCSupport property to indicate whether the operating system supports .ttc (true type font collections) files.

Remarks

This property is set if the installer detects Windows 2000 or any of the following operating systems.

JPN - 932

China - 936

Taiwan - 950

Korea - 949

Hong Kong SAR - 950.


UILevel Property

The installer sets the UILevel property to the level of the user interface. The internal UI is enabled and set by MsiSetInternalUI. This property is set to one of the following INSTALLUILEVEL data types.

INSTALLUILEVEL | Numeric value | User interface level
INSTALLUILEVEL_NONE | 2 | Completely silent installation.
INSTALLUILEVEL_BASIC | 3 | Simple progress and error handling.
INSTALLUILEVEL_REDUCED | 4 | Authored UI, wizard dialogs suppressed.
INSTALLUILEVEL_FULL | 5 | Authored UI with wizards, progress, errors.

See Also

User Interface


UpdateStarted Property

The installer sets the UpdateStarted property when changes to the system have begun for this install, including resuming a suspended install.

UI condition statements use this value to select a dialog box. If this property is set, the user is asked after an error and cancellation whether to restore or to continue later.


UpgradeCode Property

The UpgradeCode property is a GUID representing a related set of products. The UpgradeCode is used in the Upgrade Table to search for related versions of the product that are already installed.

This property is used by the RegisterProduct action.

Remarks

It is strongly recommended that authors of installation packages specify an UpgradeCode for their application.

See Also

Patching and Upgrades, Preparing an Application for Future Major Upgrades


UserLanguageID Property

The UserLanguageID property is the default language identifier for the current user. The installer sets this property by calling GetUserDefaultLangID.


USERNAME Property

The USERNAME property is a user performing installation.

Default Value

Default value may be put in the Property table. If the USERNAME property is not set, then it is set automatically using values from the registry.

Remarks

Set the NOUSERNAME property to suppress the automatic setting of USERNAME.


NOUSERNAME Property

Set the NOUSERNAME property to 1 to suppress the installer from setting of the USERNAME property. This property is used by applications that need to collect the user name at the first-run.

Default Value

Not set. The installer sets the USERNAME property automatically using values from the registry.


Version9X Property

The Version9X property gives the version number for the Windows 95, Windows 98, or Windows Millennium Edition operating systems.

The value of this property is an integer: MajorVersion * 100 + MinorVersion. The property remains undefined if the operating system is not Windows 95, Windows 98, or Windows Millennium Edition. For more information, see Operating System Property Values.

Remarks

Condition expressions can test for the version of Windows 95, Windows 98, or Windows Millennium Edition by using the property name or may verify the version by using a comparison operator.

All property names are case-sensitive. Note that the X in the name Version9X is in uppercase.


VersionNT Property

The installer sets the VersionNT property to the version number for the operating system, undefined if the operating system is not Windows NT/Windows 2000. The value is an integer: MajorVersion * 100 + MinorVersion.

Windows NT/Windows 2000 operating system dependent actions and condition expressions use this value.

See also Operating System Property Values.

Remarks

Condition expressions can test for Windows NT/Windows 2000 simply by using the property name, or may verify the version using a comparison operator.


VersionNT64 Property

The installer sets the VersionNT64 property to the version number for the operating system only if the system is running on a 64-bit computer. The property is undefined if the operating system is not 64-bit.

The value is an integer: MajorVersion * 100 + MinorVersion.

Remarks

Conditional expressions test for 64-bit Windows simply by using the property name, or by verifying the version using a comparison operator.


VirtualMemory Property

The installer sets the VirtualMemory property to the amount of available page file space in megabytes.


WindowsBuild Property

The installer sets the WindowsBuild property to the build number of the operating system. For more information, see Operating System Property Values.


WindowsFolder Property

The installer sets the WindowsFolder property to the full path to the Windows folder.

Remarks

Common values for this property are C:\Winnt (Windows NT/Windows 2000) and C:\Windows (Windows 95 and Windows 98).

This folder is local, even when configured for shared Windows.


WindowsVolume Property

The installer sets the WindowsVolume property to the volume of the windows folder. The property always ends with a backslash. This can be used to set the default location to the volume the windows folder is on because the ROOTDRIVE property does not necessarily equal this drive.


Summary Information Stream

The material in this section is intended for developers who are writing their own setup programs and developers who want to learn more about the Microsoft® Windows® Installer database tables. For general information, see About Windows Installer.

The summary information stream is used by the installer for two purposes. First, it contains information about the package that can be viewed through the Microsoft® Windows® Explorer. This information is accessible through the IStream interface. Second, it contains properties that are used by the installer to install the package. The following topics provide information about how to use the summary information stream with the installer:

  • About the Summary Information Stream
  • Using the Summary Information Stream
  • Summary Information Stream Reference


About the Summary Information Stream

The summary information stream contains information about the package that can be viewed through the Microsoft® Windows® Explorer. This information is accessible through the IStream interface. It is up to the author to provide the values for each of these properties.

The summary information stream uses COM to provide structured storage of databases. COM supports the concept of structured storage accessible through the IStream interface. Structured storage, in turn, supports the concept of property sets as a flexible method for serializing almost any information. The COM specification defines a single standard property set, summary information, which is used to populate property sheets viewable from the Windows Explorer. So, information stored in the summary information stream can be viewed by users when they right-click an installer database or transform and select Properties.

For a list of the summary property set see Summary Information Stream Property Set.

For brief descriptions of the Summary Information properties used with databases, transforms, and patches, see Summary Property Descriptions.


Summary Information Stream Property Set

The following table shows the summary information stream property set, which includes the properties, their corresponding property IDs, PIDs, types, and also explains how the installer uses these properties.

Property name | Property ID | PID | Type
Codepage Property | PID_CODEPAGE | 1 | VT_I2
Title | PID_TITLE | 2 | VT_LPSTR
Subject | PID_SUBJECT | 3 | VT_LPSTR
Author | PID_AUTHOR | 4 | VT_LPSTR
Keywords | PID_KEYWORDS | 5 | VT_LPSTR
Comments | PID_COMMENTS | 6 | VT_LPSTR
Template | PID_TEMPLATE | 7 | VT_LPSTR
Last Saved By | PID_LASTAUTHOR | 8 | VT_LPSTR
Revision Number | PID_REVNUMBER | 9 | VT_LPSTR
Last Printed Summary property | PID_LASTPRINTED | 11 | VT_FILETIME
Create Time/Date | PID_CREATE_DTM | 12 | VT_FILETIME
Last Save Time/Date | PID_LASTSAVE_DTM | 13 | VT_FILETIME
Page Count | PID_PAGECOUNT | 14 | VT_I4
Word Count | PID_WORDCOUNT | 15 | VT_I4
Character Count | PID_CHARCOUNT | 16 | VT_I4
Creating Application | PID_APPNAME | 18 | VT_LPSTR
Security | PID_SECURITY | 19 | VT_I4

The installer currently maintains three storage formats for installation packages, transforms, and patch packages. The CLSID for the storage is set to the appropriate format class for the particular format, independent of the summary information for the storage.


Summary Property Descriptions

Summary properties for installation databases and transforms are described in the following table.

Summary property | Installation database | Transform | Patch package
Title | "Installation Database" | "Transform" | "Patch"
Subject | ProductName Property | Short description of the transform that commonly contains the product's name. | Short description of the patch that commonly contains the product's name.
Author | Manufacturer Property | Manufacturer Property | Manufacturer Property
Keywords | Used by file browsers to do keyword searches for a file. Keyword set typically includes "Installer" as well as product-specific keywords. | Used by file browsers to do keyword searches for a file. Keyword set typically includes "Transform" as well as product-specific keywords. | Semicolon delimited list of sources of the patch.
Comments | "This installer database contains the logic and data required to install <product name>." | "This transform contains the logic and data required to modify <product name>." | "This patch contains the logic and data required to modify <product name>."
Template (REQUIRED) | Platform and language versions supported by database. Specifying more than one language results in a multi-language install. See Template for syntax. | Database platform and language versions compatible with the transform. May be left blank if there are no restrictions. Only one language can be specified. See Template for syntax. | Semicolon delimited list of the product codes that can accept the patch.
Last Saved By | Set during an administrative installation to identify the last person to modify the database. | Specifies the platform and language of the transformed database using the same syntax as the Template Summary property. | Semicolon delimited list of transform sub-storage names in the order they are applied.
Revision Number (REQUIRED) | Package code for the installer package. | Lists the product code GUIDs and version of the new and original products and the upgrade code GUID. The list is separated by semicolons as follows. Original-Product-Code Original-Product-Version;New-Product Code New-Product-Version; Upgrade-Code | Specifies the GUID patch code for the patch. This is followed by a list of patch code GUIDs for patches that are removed when this patch is applied. The patch codes are concatenated with no delimiters separating GUIDs in the list.
Last Printed | May be set to the date and time during an administrative installation to record when the administrative image was created. | NULL | NULL
Create Time/Date | Time and date when the installer database was created. | Time and date when the transform was created. | Time and date when patch file was created.
Last Saved Time/Date | Initially NULL. Each time a user changes an installation database the value is updated to the current system time/date at the time the installer database was saved. | Initially NULL. Each time a user changes a transform the value is updated to the current system time/date at the time the transform database was saved. | Initially NULL. Each time a user changes a patch file the value is updated to the current system time/date at the time the patch file was saved.
Page Count (REQUIRED) | Minimum required installer version. For the 1.0 version of the installer, this property should be set to an integer of 100. | Minimum installer version required to process the transform. Set to the greater of the two Page Count property values belonging to the databases used to generate the transform. | NULL
Word Count (REQUIRED) | Type of source file image. Stored in place of standard Count property. This property is a bit field. See the Word Count topic for the values. | NULL | For a patch package, the Word Count Summary Property specifies the patch engine that was used to create the patch files. The default value is 1 and indicates that MSPATCH was used to create the patch. A value of "2" means that the patch is using smaller, optimized, files available only with Windows Installer version 1.2 or later. A patch with a Word Count of "2" fails immediately if used with a Windows Installer version less than 1.2.
Character Count | NULL | Upper word contains transform validation flags. Lower word contains error condition flags. | NULL
Creating Application | Application used to create the installer database. In general the value is the name of the software used to author this database. | The software used to create the transform. | The software used to create the patch.
Security | 2 - Recommended read-only. | 4 - Enforced read-only. | 4 - Enforced read-only.
Codepage | Identifies the code page used to display the Summary Information. | Identifies the code page used to display the Summary Information. | Identifies the code page used to display the Summary Information.


Using the Summary Information Stream

This section describes which functions in the Microsoft® Windows® installer API can call the summary information stream properties. For more information on the summary information stream and how it works with databases, see About the Summary Information Stream.

  • It is important to remember that the installer contains different types of databases, and some properties of the summary information stream have different meanings with different databases. For more information, see Summary Property Descriptions.
  • When a database is opened as the output of another database, the summary information stream of the output database is actually a read-only mirror of the original database and thus cannot be changed. Additionally, it will not be persisted with the database. To create or modify the summary information for the output database it must be closed and re-opened.

The following steps describe how to use the summary information stream functions:

To use the summary information stream properties

  1. Obtain a handle to the summary information stream database by calling the MsiGetSummaryInformation function.
  2. Call the MsiSummaryInfoGetPropertyCount function to obtain the number of existing properties.
  3. Call the MsiSummaryInfoGetProperty function to view a single summary information property.
  4. Call the MsiSummaryInfoSetProperty function to set a single property
  5. Call the MsiSummaryInfoPersist function to save the summary information property.


Summary Information Stream Reference

The following list shows the summary information stream properties for the Microsoft® Windows® Installer:

  • Author Summary Property
  • Character Count Summary Property
  • Codepage Summary Property
  • Comments Summary Property
  • Create Time/Date Summary Property
  • Creating Application Summary Property
  • Keywords Summary Property
  • Last Printed Summary Property
  • Last Saved By Summary Property
  • Last Saved Time/Date Summary Property
  • Word Count Summary Property
  • Page Count Summary Property
  • Revision Number Summary Property
  • Security Summary Property
  • Subject Summary Property
  • Template Summary Property
  • Title Summary Property


Author Summary Property

The Author Summary property conveys to a file browser the manufacturer of the installation database. This value is typically set from the installer property Manufacturer.


Character Count Summary Property

The Character Count Summary property is only used in transforms. This part of the summary information stream is divided into two 16-bit words. The upper word contains the transform validation flags. The lower word contains the transform error condition flags.


Codepage Summary Property

The Codepage Summary property is the numeric value of the ANSI code page used for any strings that are stored in the summary information. Note that this is not the same code page for strings in the installation database. The Codepage Summary property is used to translate the strings in the summary information into Unicode when calling the Unicode API functions. The Codepage Summary property must be set before any string properties are set in the summary information.


Comments Summary Property

The Comments Summary property conveys the general purpose of the installer database. By convention, the value for this summary property is set to the following:

"This installer database contains the logic and data required to install <product name>."

where <product name> is the name of the product being installed. In general the value for this summary property only changes in the product name, nothing else.


Create Time/Date Summary Property

The Create Time/Date Summary property conveys when the installer database was created.


Creating Application Summary Property

The Creating Application Summary property conveys which application created the installer database. In general the value for this summary property is the name of the software used to author this database.


Keywords Summary Property

This summary property is used by file browsers to hold keywords that permit the database file to be found in a keyword search. The set of keywords typically includes "Installer" as well as product-specific keywords, and may be localized.


Last Printed Summary Property

Last Printed Summary property can be set to the date and time during an administrative installation to record when the administrative image was created. For non-administrative installations this property is the same as the Create Time/Date Summary property.


Last Saved By Summary Property

The installer sets the Last Saved By Summary Property to the value of the LogonUser property during an administrative installation. The installer never uses this property and a user never needs to modify it. Developers of a database editing tool may use this property to track the last person to modify the database. This property should be left set to Null in a final shipping database.

In a transform, this summary property contains the platform and language ID(s) that a database should have after it has been transformed. The property specifies to what the Template should be set in the new database.


Last Saved Time/Date Summary Property

The Last Saved Time/Date Summary property conveys when the last time the installer database was modified. Each time a user changes an installation the value for this summary property is updated to the current system time/date at the time the installer database was saved. Initially the value for this summary property is set to NULL to indicate that no changes have yet been made.


Word Count Summary Property

The Word Count Summary property indicates the type of source file image. If this property is not present, it defaults to 0. Note that this property is stored in place of the standard Count property.

This property is a bit field. New bits may be added in the future. At present the following bits are available.

Bit | Value | Description
Bit 0 | 0 1 | Long file names. Short file names.
Bit 1 | 0 2 | Source is uncompressed. Source is compressed.
Bit 2 | 0 4 | Source is original media. Source is a administrative image created by an administrative installation.

These are combined to give the Word Count Summary property one of the following values indicating a type of source file image.

Property value | Type of source file image
0 | Original source using long file names. Matches tree in Directory table.
1 | Original source using short file names. Matches tree in Directory table.
2 | Compressed source files using long file names. Matches cabinets and files in the Media table.
3 | Compressed source files using short file names. Matches cabinets and files in the Media table.
4 | Administrative image using long file names. Matches tree in Directory table.
5 | Administrative image using short file names. Matches tree in Directory table.

Note that if the package is marked as compressed (Bit 1 is set), the installer only installs files located at the root of the source. In this case, even files marked as uncompressed in the File Table must be located at the root to be installed. To specify a source image that has both a cabinet file (compressed files) and uncompressed files that match the tree in the Directory table, mark the package as uncompressed by leaving Bit 1 unset (value=0) in the Word Count Summary property and set msidbFileAttributesCompressed (value=16384) in the Attributes column of the File table for each file in the cabinet.

For a patch package, the Word Count Summary property specifies the patch engine that was used to create the patch files. The default value is 1 and indicates that MSPATCH was used to create the patch. A value of "2" means that the patch is using smaller, optimized, files available only with Windows Installer version 1.2 or later. A patch with a Word Count of "2" fails immediately if used with a Windows Installer version earlier than 1.2.

This summary property is REQUIRED.


Page Count Summary Property

For an installation package, the Page Count Summary property contains the minimum installer version required. For Windows Installer version 1.0, this property must be set to the integer 100. For 64-bit Windows Installer Packages, this property must be set to the integer 150.

For a transform package, the Page Count Summary property contains minimum installer version required to process the transform. Set to the greater of the two Page Count Summary property values belonging to the databases used to generate the transform.

The Page Count Summary property is set to Null in patch packages.

This summary property is REQUIRED.


Revision Number Summary Property

The Revision Number Summary property contains the package code for the installer package. The package code is a unique identifier of the installer package.

The Revision Number Summary property of a patch package specifies the GUID patch code for the patch. This is followed by a list of patch code GUIDs for obsolete patches that are removed when this patch is applied. The patch codes are concatenated with no delimiters separating GUIDs in the list.

The Revision Number Summary property of a transform package lists the product code GUIDs and version of the new and original products and the upgrade code GUID. The list is separated with semicolons as follows.

Original-Product-Code Original-Product-Version ; New-Product Code New-Product-Version; Upgrade-Code

This summary property is REQUIRED.


Security Summary Property

The Security Summary property conveys whether the package should be opened as read-only. The database editing tool should not modify a read-only enforced database and should issue a warning at attempts to modify a read-only recommended database. The following values of this property are applicable to Windows Installer files.

Value | Description
0 | No restriction
2 | Read-only recommended
4 | Read-only enforced

This property should be set to read-only recommended (2) for an installation database and to read-only enforced (4) for a transform or patch.


Subject Summary Property

This summary property conveys to a file browser the product that can be installed using the logic and data in this installer database. For example, the value of the summary property for Microsoft® Office 97 would be; "Microsoft Office 97 Professional". This value is typically set from the installer property ProductName.


Template Summary Property

The Template Summary indicates the platform and language versions supported by the database.

The syntax of the Template Summary property information is:

[platform property][,platform property][,...];[language id][,language id][,...].

For example, the following are all valid values for the Template Summary property:

  • Alpha,Intel64;1033
  • Alpha,Intel;1033
  • Intel,Alpha;1033
  • Alpha;1033
  • Intel;1033
  • Intel64;1033
  • ;1033
  • ;
  • Alpha;1033,2046
  • Intel ;1033,2046
  • Intel64;1033,2046
  • Intel;0

Note The Alpha platform is not supported by Windows Installer version 1.1 or later versions.

If this is a 64-bit Windows Installer, enter Intel64 in the Template Summary property. Note that an installation package cannot have both the Intel and Intel64 properties set.

If the current platform does not match one of the platforms specified then the installer will not process the package. Not specifying a platform implies that the package is platform-independent.

Entering 0 in the language ID field of the Template Summary property, or leaving this field empty, indicates that the package is language neutral.

There are variations of this property depending on whether it is in a source installer database or a transform.

Source Installer Database
In a source installer database any number of languages may be specified. If more than one language is specified then a multi-language install is performed. Listing only one language specifies a single-language install.
Transform
In a transform file only one language may be specified. The specified platform and language determine whether a transform can be applied to a particular database. The platform property and the language property can be left blank if no transform restriction relies on them to validate the transform.

This summary property is REQUIRED.


Title Summary Property

The Title Summary property briefly describes the type of installer package. Phrases such as "Installation Database" or "Transform" or "Patch" may be used for this property.


Automation Interface

The material in this section is intended for developers who are writing their own setup programs and for developers who want to learn more about the Microsoft® Windows® Installer database tables.

For information about automation and access to C++ Libraries, see the section: About the Automation Interface.

For information about using automation and creating the Installer object, see the section Using the Automation Interface.

For reference material for installer objects, see the section: Automation Interface Reference.


About the Automation Interface

An Installer object must be created initially to load the automation support required to access the installer components through COM. This object provides wrappers to create the top-level objects and access their methods. These wrappers simply provide parameter translations to expose the installer functions in a manner consistent with Microsoft® Visual Basic® without changing the behavior of the methods.

Whenever possible, a pair of Get and Set C++ methods are exposed to Visual Basic as a single property. In some cases C++ methods taking an index argument are exposed as an indexed property. Many C++ methods return the result through a parameter because the return value is used for the error return. However, in Visual Basic, errors are handled by a separate mechanism, and the result is always passed in the return value.

For information about using automation and creating the Installer object, see Using the Automation Interface.

For reference material for the Microsoft® Windows® Installer objects, see Automation Interface Reference.


Using the Automation Interface

To access automation, the DLL must be self-registered. The COM ProgId used to create the Installer object is WindowsInstaller.Installer.

For information about automation and access to C++ Libraries, see About the Automation Interface.

For reference material for the Microsoft® Windows® Installer objects, see Automation Interface Reference.


Automation Interface Reference

This section contains reference material for Microsoft® Windows® Installer objects:

  • Windows Installer Object Model
  • Database Object
  • FeatureInfo Object
  • Session Object
  • Installer Object
  • Record Object
  • SummaryInfo Object
  • UIPreview Object
  • View Object
  • StringList Object


Windows Installer Object Model

The object model for the Windows Installer is organized as follows.

ComponentQualifiers, Components, Features, and Products are StringList collections, which are just an array of strings, such as a user-defined collection. These strings represent names of elements that are core to the installer.


Database Object

The Database object accesses an installer database.

The Database object is released when it is either taken out of scope or when the object variable associated with it is set to null. The Commit method must be called before the Database object is released to write out all persistent changes. If the Commit method is not called, the installer performs an implicit rollback upon object destruction.

To Query API Sequencing

The client can use the following procedure for data access:

  1. Obtain a Database object by calling the OpenDatabase of the Installer object.
  2. Initiate a query using a SQL string by calling the OpenView method of the Database object.
  3. Set query parameters in a Record Object and execute the database query by calling the Execute method of the View object. This produces a result that can be fetched or updated.
  4. Call the Fetch method of the View object repeatedly to return Record objects.
  5. Update database rows of a Record object obtained by the Fetch method using the Modify method of the View object.
  6. Release the query and any unfetched records by calling the Close method of the View object.
  7. Persist any database updates by calling the Commit method of the Database object.

Properties

DatabaseState

PrimaryKeys

SummaryInformation (Database Object)

TablePersistent

Methods

ApplyTransform

Commit

CreateTransformSummaryInfo

EnableUIPreview

Export

GenerateTransform

Import

Merge

OpenView


ApplyTransform Method

The ApplyTransform method of the Database object applies the transform to this database.

Syntax

object.ApplyTransform(storage, errorConditions)

Parts

object
Database object
storage
Required Database object containing the transform.
errorConditions
Specifies the error conditions that are to be suppressed. Specify as a combination of the following integer values.
Error condition | Value | Meaning
msiTransformErrorAddExistingRow | 0x0001 | Adding a row that already exists.
msiTransformErrorDeleteNonExistingRow | 0x0002 | Deleting a row that does not exist.
msiTransformErrorAddExistingTable | 0x0004 | Adding a table that already exists.
msiTransformErrorDeleteNonExistingTable | 0x0008 | Deleting a table that does not exist.
msiTransformErrorUpdateNonExistingRow | 0x0010 | Updating a row that does not exist.
msiTransformErrorChangeCodePage | 0x0020 | Transform and database code pages do not match and neither has a neutral code page.
msiTransformErrorViewTransform | 0x0100 | Create the temporary _TransformView table.

Remarks

The ApplyTransform method delays transforming tables until the last possible moment. The steps taken in ApplyTransform are to immediately transform the table and column catalogs for the database. The table and column catalogs are updated according to what table is added or deleted and what column is added (no deletion of columns is allowed). If a table is currently loaded in memory and needs to be transformed, it is transformed. Else, the table state is set to that requiring a transform so that when the table is loaded, or when the database is committed, the transform is applied. Transform in this instance means that the actual (row) data of the table is added, deleted, or updated.

See Also

Transforms


Commit Method

The Commit method of the Database object finalizes the persistent form of the database. All persistent data is written to the writeable database, and no temporary columns or rows are written. This method has no effect on a database opened as read-only. This method can be called multiple times to save the current state of tables loaded into memory. When the database is finally closed, any changes made subsequent to the last Commit are rolled back. This method is normally called prior to shutdown when all database changes have been finalized.

Syntax

object.Commit

Parts

object
Database object


CreateTransformSummaryInfo Method

The CreateTransformSummaryInfo method of the Database object creates and populates the summary information stream of an existing transform file. This method fills in the properties with the base and reference ProductCode and ProductVersion.

Syntax

object.CreateTransformSummaryInfo(reference, storage, errorConditions, validation )

Parts

object
Database that includes the changes.
reference
Required database that does not include the changes.
storage
The name of the generated transform file. This is optional.
errorConditions
Required error conditions that should be suppressed when the transform is applied. Combine one or more of the following error condition values.
Error condition name | Value | Description
msiTransformErrorNone | 0 | None of the following conditions.
msiTransformErrorAddExistingRow | 1 | Adding a row that already exists.
msiTransformErrorDeleteNonExistingRow | 2 | Deleting a row that doesn't exist.
msiTransformErrorAddExistingTable | 4 | Adding a table that already exists.
msiTransformErrorDeleteNonExistingTable | 8 | Deleting a table that doesn't exist.
msiTransformErrorUpdateNonExistingRow | 16 | Updating a row that doesn't exist.
msiTransformErrorChangeCodepage | 32 | Transform and database code pages do not match and neither code page is neutral.

validation
Required when the transform is applied to a database; shows which properties should be validated to verify that this transform can be applied to the database. The properties are all contained in the Summary Information Stream Property Set.

Combine one or more of the following values.
Validation flag | Value | Description
msiTransformValidationNone | 0 | No validation done.
msiTransformValidationLanguage | 1 | Default language must match base database.
msiTransformValidationProduct | 2 | Product must match base database.

To validate product version, first choose one or more of these three flags to indicate how much of the version is to be verified.
Validation flag | Value | Description
msiTransformValidationMajorVer | 8 | Check major version only.
msiTransformValidationMinorVer | 16 | Check major and minor version only.
msiTransformValidationUpdateVer | 32 | Check major, minor, and update versions.

Then choose one of the following to indicate the required relationship between the product version of the database the transform is being applied to and that of the base database.
Validation flag | Value | Description
msiTransformValidationLess | 64 | Applied version < base version
msiTransformValidationLessOrEqual | 128 | Applied version <= base version
msiTransformValidationEqual | 256 | Applied version = base version
msiTransformValidationGreaterOrEqual | 512 | Applied version >= base version
msiTransformValidationGreater | 1024 | Applied version > base version

To validate that the transform is being applied to a package having the appropriate UpgradeCode, set the following flag.
Validation flag | Value | Description
msiTransformValidationUpgradeCode | 2048 | Validates that the transform is the appropriate UpgradeCode.

Remarks

To create a summary information stream for a transform, the ProductCode and ProductVersion properties must be defined in the Property tables of both the base and reference databases. If msiTransformValidationUpgradeCode is used, the UpgradeCode property must be defined in both databases.

See Also

Transforms


DatabaseState Property

The DatabaseState property of the Database object is a read-only property.

This property returns the persistence state of the database as one of the following parameters.

Database state | Value | Description
msiDatabaseStateRead | 0 | Database opens as read-only. Changes to persistent data are not permitted and temporary data is not saved.
msiDatabaseStateWrite | 1 | Database is fully operational for read and write.

Syntax

object.DatabaseState

Parts

object
Database object.


EnableUIPreview Method

The EnableUIPreview method of the Database object facilitates the authoring of dialog boxes and billboards by providing the support needed to view UI dialog boxes stored in the installer database. The method starts the preview mode by returning a preview object. The preview mode ends when the preview object is released.

Syntax

object.EnableUIPreview

Parts

object
Database object


Export Method

The Export method of the Database object copies the structure and data from a specified table to a text archive file.

Syntax

object.Export(table, path, file)

Parts

object
Database object
table
Required name of the database table. Case-sensitive if using the installer database.
path
Required string that is the path to the folder where the text file will be placed.
file
Required name of the file to be created. This does not include the folder, as that must be set in the path object.


GenerateTransform Method

The GenerateTransform method of the Database object creates a transform that, when applied to the object database, results in the reference database. The transform is stored in the storage object.

If the transform is to be applied during an installation you must use the CreateTransformSummaryInfo method to populate the summary information stream.

Syntax

object.GenerateTransform(reference, storage)

Parts

object
Database that includes the changes.
reference
Required database that does not include the changes.
storage
The name of the generated transform file. This is optional.

Remarks

A transform can add non-primary key columns to the end of a table. A transform cannot be created that adds primary key columns to a table. A transform cannot be created that changes the order, names, or definitions of columns.

This method returns a Boolean value. It returns TRUE if a transform is generated. It returns FALSE if a transform is not generated because there are no differences between the two databases. If the method fails, it generates an error.

See Also

Transforms


Import Method

The Import method of the Database object imports a database table from a text archive file, dropping any existing table.

Syntax

object.Import(path, file)

Parts

object
Database object.
path
Required folder where the text file is present.
file
Required name of the file to be imported. This does not include the folder, as that must be set in the path object. The table name is specified within the file.

See Also

MsiDatabaseImport


Merge Method

The Merge method of the Database object merges the reference database with the base database.

Syntax

object.Merge(reference, errorTable)

Parts

object
Database object
reference
Required Database object to be merged into the base.
errorTable
Optional name of a table to contain the names of the tables containing merge conflicts, the number of conflicting rows within the table, and a reference to the table with the merge conflict.

Remarks

Merge does not copy over embedded cabinet files or embedded transforms from the reference database into the target database. Embedded data streams that are listed in the Binary table or Icon table are copied from the reference database to the target database. Storages embedded in the reference database are not copied to the target database.

If no table is provided, the general error message provides the number of tables containing merge conflicts. Any table can be passed in, but all other columns must be nullable because the operation to update the Error table fails if a column is not nullable. A newly created table can be passed in as well because the Merge method automatically creates the columns it uses if merge conflicts are found. Two columns are used for presenting merge conflicts. The first column is the table name and the primary key column. The second column is the number of rows of that table that have merge failures.

If tables of the same name in both databases do not match in the number of primary keys, the column types, the number of columns, or the column names, the Merge method fails and posts an error message stating what occurred.

For the Error table to remain, the error handler must commit the database to which the Error table belongs. However, this commit should be done after using the third column to obtain the references to those tables where merge conflicts occurred.


OpenView Method (MSIDatabase Object)

Microsoft Windows Installer

OpenView Method

The OpenView method of the Database object returns a View object representing the query specified by a SQL string.

Syntax

object.OpenView(sql)

Parts

object
Database object
sql
Required SQL query string.

Remarks

For information about SQL syntax implemented in the installer, see SQL Syntax.

See Also

SQL Syntax


PrimaryKeys Property

The PrimaryKeys property of the Database object returns an Record object containing the table name in field 0 and the column names (comprising the primary keys) in succeeding fields corresponding to their column numbers. The field count of the record is the count of primary key columns.

Syntax

object.PrimaryKeys(table)

Parts

object
Database object
table
Required name of an existing table. An error is generated if the table does not exist.

Remarks

The PrimaryKeys property cannot be used with the _Tables table or the _Columns table.


SummaryInformation Property (Database Object)

The SummaryInformation property of the Database object returns a SummaryInfo object that can be used to examine, update, and add properties to the summary information stream.

Syntax

object.SummaryInformation(maxProperties)

Parts

object
Database object
maxProperties
The maximum number of properties to be added or modified. This parameter is required and used to allocate sufficient working memory during the stream generation. It is not required to store this number of properties. A value of zero must be used if the database is opened read-only to prevent the stream from being updated.

Remarks

If a value of maxProperties greater than 0 is used to open an existing summary information stream, the Persist method must be called before closing the object. Failing to do this will lose the existing stream information.


TablePersistent Property

The TablePersistent property of the Database object returns the persistence state of the table as one of the following parameters.

Table state | Value | Description
msiEvaluateConditionFalse | 0 | Table is temporary.
msiEvaluateConditionTrue | 1 | Table is persistent.
msiEvaluateConditionNone | 2 | Table is not in the database.
msiEvaluateConditionError | 3 | Invalid or missing table name.

Syntax

object.TablePersistent table

Parts

object
Database object
table
Required name of the table.


FeatureInfo Object

The FeatureInfo object contains information regarding the targeted feature and is created from the Session object using the FeatureInfo Method.

Properties

Title

Description

Attributes


Attributes Property (FeatureInfo Object)

The Attributes property is a read-write property that returns the value for the feature in the Attributes column of the Feature table.

Syntax

object.Attributes

Parts

object
FeatureInfo object


Description Property (FeatureInfo Object)

The Description property is a read-only property that returns the description of the feature in the Description column of the Feature table.

Syntax

object.Description

Parts

object
FeatureInfo object


Title Property

The Title property is a read-only property that returns the title of the feature in the Title column of the Feature table.

Syntax

object.Title

Parts

object
FeatureInfo object


Session Object

The Session object controls the installation process. It opens the install database, which contains the installation tables and data. This object is associated with a standard set of action functions, each performing particular operations on data from one or more tables. Additional custom actions may be added for particular product installations. The basic engine function is a sequencer that fetches sequential records from a designated sequence table, evaluates any specified condition expression, and executes the designated action. Actions not recognized by the engine are deferred to the UI handler object for processing, usually dialog box sequences.

Note that only one Session object can be opened by a single process.

Properties

ComponentCurrentState

ComponentRequestState

Database

FeatureCost

FeatureCurrentState

FeatureRequestState

FeatureValidStates

Installer

Language (Session Object)

Mode

ProductProperty

Property (Session Object)

SourcePath

TargetPath

VerifyDiskSpace

Methods

DoAction

EvaluateCondition

FeatureInfo

FormatRecord

Message

Sequence

SetInstallLevel


ComponentCurrentState Property

The ComponentCurrentState property of the Session object is a read-only property that returns the current installed state of the designated component. For state values, see the ComponentRequestState property.

Syntax

object.ComponentCurrentState(component)

Parts

object
Session object
component
Required string name of the requested component, primary key into the Component table.

See Also

ComponentRequestState property


ComponentRequestState Property

The ComponentRequestState property of the Session object obtains or requests a change in the Action state of a row in the Component table.

Syntax

object.ComponentRequestState(component)

Parts

object
Session object
component
Required string name of the component item, primary key of the Component table.

Remarks

Selection state | Value | Description
Null | Null | Requests that no action be taken for this item.
msiInstallStateAbsent | 2 | Item is to be removed.
msiInstallStateLocal | 3 | Item is to be installed locally.
msiInstallStateSource | 4 | Item is to be installed and run from the source media.
msiInstallStateDefault | 5 | If installed, the item is to be reinstalled in the same state.


Database Property

The Database property of the Session object is a read-only property that returns the database for the current install session as a Database object.

Syntax

object.Database

Parts

object
Session object


DoAction Method

The DoAction method of the Session object executes the action function corresponding to the name supplied. If a Null action name is supplied, the engine uses the uppercase value of the ACTION property as the action to perform. If no property value is defined, the default action is performed, currently defined as INSTALL. This method returns an integer enumeration.

Syntax

object.DoAction(action)

Parts

object
Session object
action
Required string name of the action to execute. Case-sensitive.

Remarks

Status | Value | Description
msiDoActionStatusNoAction | 0 | Action not invoked, most likely does not exist.
msiDoActionStatusSuccess | 1 | IDOK, completed actions successfully.
msiDoActionStatusUserExit | 2 | IDCANCEL, user terminated prematurely.
msiDoActionStatusFailure | 3 | IDABORT, unrecoverable error occurred.
msiDoActionStatusSuspend | 4 | IDRETRY, sequence suspended, to be resumed later.
msiDoActionStatusFinished | 5 | IDIGNORE, skip remaining actions, not an error.
msiDoActionStatusWrongState | 6 | Calling sequence error, not in initialized state.
msiDoActionStatusBadActionData | 7 | Invalid action table condition or missing custom action.

Actions that update the system, such as the InstallFiles and WriteRegistryValues actions, cannot be run by calling the DoAction method. The exception to this rule is if the DoAction method is called from a custom action that is scheduled in the InstallExecuteSequence table between the InstallInitialize and InstallFinalize actions. Actions that do not update the system, such as AppSearch or CostInitialize, can be called.


EvaluateCondition Method

The EvaluateCondition method of the Session object evaluates a logical expression containing symbols and values and returns an integer of the enumeration msiEvaluateConditionErrorEnum.

Syntax

object.EvaluateCondition(condition)

Parts

object
Session object
condition
Required string containing the logical expression. For information on the syntax of conditional statements, see Conditional Statement Syntax.

Remarks

Table condition | Value | Description
msiEvaluateConditionFalse | 0 | Table is temporary.
msiEvaluateConditionTrue | 1 | Table is persistent.
msiEvaluateConditionNone | 2 | Table is not present in the database.
msiEvaluateConditionError | 3 | Invalid or missing table name.

Feature and component state | Value | Description
Null | Null | Feature or component is not present.
msiInstallStateAbsent | 2 | Feature or component is not present.
msiInstallStateLocal | 3 | Feature or component is on a local machine.
msiInstallStateSource | 4 | Feature or component runs from source.

Note These states are not set until the SetInstallLevel method is called, either directly or by the CostFinalize action. Therefore, state checking is generally only useful in conditional expression in an action sequence table.

See Also

Conditional Statement Syntax


FeatureCost Property

The FeatureCost property of the Session object returns the total amount of disk space (in units of 512 bytes) required by the specified feature and its parent features (up to the root of the Feature table). For each feature, the total cost is made up of the disk costs attributed to every component linked to the feature.

Syntax

object.FeatureCost(feature, costTree, state)

Parts

object
Session object
feature
Required string name of the feature item whose cost is to be retrieved.
costTree
Required portion of the feature tree branch to cost, one of the following:
Part to cost | Value | Description
msiCostTreeSelfOnly | 0 | Cost feature.
msiCostTreeChildren | 1 | Cost children features.
msiCostTreeParents | 2 | Cost parent features.

state
Required element that specifies the action state to use when determining the feature cost. For example, if msiInstallStateLocal is specified, FeatureCost returns the disk space required if the specified feature and all its parent features were to be installed locally.
Action state name | Value | Description
msiInstallStateLocal | 3 | Disk space required if the specified feature and all its parent features were to be installed locally
msiInstallStateSource | 4 | Disk space required if the specified feature and all its parent features were to be installed to run from source.
msiInstallStateDefault | 5 | If installed, the item is to be reinstalled in the same state.


FeatureCurrentState Property

The FeatureCurrentState property of the Session object is a read-only property that returns the current installed state of the designated feature. For state values, see the FeatureRequestState property.

Syntax

object.FeatureCurrentState(feature)

Parts

object
Session object
feature
Required string name of the requested feature, and a primary key into the Feature table.

See Also

FeatureRequestState property


FeatureInfo Method

The FeatureInfo method returns a FeatureInfo Object containing descriptive information for the specified feature.

Syntax

object.FeatureInfo(Feature)

Parts

object
Session object
Feature
Identifies the feature of interest.

See Also

MsiGetFeatureInfo


FeatureRequestState Property

The FeatureRequestState property of the Session object obtains or requests a change in the Select state of a feature's record (and of the feature's subrecords) in the Feature table. In turn, the Action state of all the components linked to the changed feature records are also updated appropriately, based on the new feature Select state. FeatureRequestState can also be used to configure all features at once by specifying the keyword ALL instead of a specific feature name.

Syntax

object.FeatureRequestState(strFeature)

Parts

object
Session object
strFeature
Required string specifying the name of the feature to be configured. Alternatively, the reserved word ALL (not case sensitive) can be used, indicating that all features should be configured to the state specified by the msiInstallState parameter. For example, if msiInstallStateAbsent is specified in the msiInstallState parameter, and ALL is specified in the strFeature parameter, the entire product is removed.
Selection state name | Value | Description
Null | Null | Requests that no action be taken for this item.
msiInstallStateAbsent | 2 | Item is to be removed.
msiInstallStateLocal | 3 | Item is to be installed locally.
msiInstallStateSource | 4 | Item is to be installed and run from the source media.
msiInstallStateDefault | 5 | If the feature is installed, reinstall it in the same state.

Remarks

The SetInstallLevel method must be called before calling FeatureRequestState.

When FeatureRequestState is called, the Engine attempts to set the Action state of each component tied to the specified feature to the specified state, as best as possible. However, there are common situations when the request cannot be fully honored. For example, suppose a feature is tied to two components, Component A and Component B (via the FeatureComponents table). Also suppose that Component A is authored with a RunFromSource option of irsLocalOnly, and Component B is irsSourceOnly. In this case, if FeatureRequestState is called with a requested state of either msiInstallStateLocal or msiInstallStateSource, there is no way that the request can be fully honored for both components. However, both components can be turned ON with component A set to msiInstallStateLocal and component B set to msiInstallStateSource.

If more than one feature is linked to a single component, the final Action state of that component is determined as follows: If at least one feature calls for the component to be installed locally, it is installed msiInstallStateLocal. If at least one feature calls for the component to be run from the source media, it is installed msiInstallStateSource. If at least one feature calls for the removal of the component, the action state is msiInstallStateAbsent. For more information on how features are selected for installation, see the Feature table.

See Also

Feature table


FeatureValidStates Property

The FeatureValidStates property of the Session object returns an integer representing bit flags with each relevant bit representing a valid installation state for the specified feature.

Syntax

object.FeatureValidStates(feature)

Parts

object
Session object
feature
Required string name of the feature item whose valid installation states are to be retrieved.

Remarks

The return value is composed of bit flags as follows. Bit 0: if set, Local is a valid state. Bit 1: if set, Source is a valid state.

The FeatureValidStates property only succeeds after the installer has called the CostInitialize and CostFinalize actions.

The GetFeatureValidStates method determines state validity by querying all the components that are linked to the specified feature (without taking into account the current installed state of any component). If any of these components has a value of irsOptional in the RunFromSource column, or if at least one component is marked irstLocalOnly and at least one other component is marked irsSourceOnly, then both msiInstallStateLocal and msiInstallStateSource are valid states for the feature. If all components are set to irsLocalOnly, then msiInstallStateLocal is the only valid state. If all components are set to irsSourceOnly, then msiInstallStateSource is the only valid state.


FormatRecord Method

The FormatRecord method of the Session object returns a formatted string from a template and record data.

Syntax

object.FormatRecord(record)

Parts

object
Session object
record
Required Record object containing a template and data to be formatted. The template string must be set in field 0 followed by any referenced data parameters.

Remarks

The FormatRecord method uses the following format process.

Parameters to be formatted are enclosed in square brackets [..]. The square brackets can be iterated because the substitutions are resolved from inside out.

If a part of the string is enclosed in curly braces { } and contains no square brackets, the part is left unchanged, including the curly braces.

If a part of the string is enclosed in curly braces and contains one or more property names, and if all the properties are found, the text (with the resolved substitutions) is displayed without the curly braces. If any of the properties are not found, all the text in the curly braces and the braces themselves are removed.

To format strings using the FormatRecord method

  1. The numeric parameters are substituted by replacing the marker with the value of the corresponding record field, with missing or Null values producing no text.
  2. The string that results is processed by replacing the non-record parameters with the corresponding values, as noted in the following descriptions.
    • If a substring of the form "[propertyname]" is encountered, it is replaced by the value of the property.
    • If a substring of the form "[%environmentvariable]" is found, the value of the environment variable is substituted.
    • If a substring of the form [#filekey] is found, it is replaced by the full path of the file, with the value filekey used as a key into the File table. The value of [#filekey] remains blank and is not replaced by a path until the installer runs the CostInitialize action, FileCost action, and CostFinalize action. The value of [#filekey] depends upon the installation state of the component to which the file belongs. If the component is being run from source, the value is the path to the source location of the file. If the component is being run locally, the value is the path to the target location of the file after installation. If the component is absent, the path is blank. For more information about checking the installation state of components see Checking the Installation of Features, Components, Files.
    • If a substring of the form [$componentkey] is found, it is replaced by the install directory of the component, with the value componentkey used as a key into the Component table. The value of [$componentkey] remains blank and is not replaced by a directory until the installer runs the CostInitialize action, FileCost action, and CostFinalize action. The value of [$componentkey] depends upon the installation state of the component. If the component is being run from source, the value is the source directory of the file. If the component is being run locally, the value is the target directory after installation. If the component is absent, the value is left blank. For more information about checking the installation state of components see Checking the Installation of Features, Components,
    • If a substring of the form "[\c]" is found, it is replaced by the character without any further processing. Only the first character after the backslash is kept; everything else is removed.

See Also

Formatted, Column Data Types


Installer Property

The read-only Installer property of the Session object returns the active Installer object.

Syntax

object.Installer

Parts

object
Session object


Language Property (Session Object)

The Language property of the Session object is a read-only property that represents the numeric language ID used by the current install session.

Syntax

object.Language

Parts

object
Session object


Message Method

The Message method of the Session object performs any enabled logging operations and defers execution to the UI handler object associated with the engine. Logging may be selectively enabled for the various message types. See the EnableLog method.

If record field 0 contains a formatting string, it is used to format the data in the other fields. Else if the message is an error, warning, or user message, an attempt is made to find a message template in the Error table for the current database using the error number found in field 1 of the record for message types and return values.

Syntax

object.Message(kind, record)

Parts

object
Session object
kind
Required message type, one of msiMessageTypeEnum. This must be one of the following values.
Constant | Hexadecimal | Description
msiMessageTypeFatalExit | &H00000000 | Premature termination, possibly fatal out of memory.
msiMessageTypeError | &H01000000 | Formatted error message, [1] is message number in Error table.
msiMessageTypeWarning | &H02000000 | Formatted warning message, [1] is message number in Error table.
msiMessageTypeUser | &H03000000 | User request message, [1] is message number in Error table.
msiMessageTypeInfo | &H04000000 | Informative message for log, not to be displayed.
msiMessageTypeFilesInUse | &H05000000 | List of files in use that need to be replaced.
msiMessageTypeResolveSource | &H06000000 | Request to determine a valid source location.
msiMessageTypeOutOfDiskSpace | &H07000000 | Insufficient disk space message.
msiMessageTypeActionStart &H08000000 Start of action,
[1] action name,
[2] description,
[3] template for ACTIONDATA messages.
msiMessageTypeActionData | &H09000000 | Action data. Record fields correspond to the template of ACTIONSTART message.
msiMessageTypeProgress | &H0A000000 | Progress bar information. See the description of record fields below.
msiMessageTypeCommonData &H0B000000 To enable the Cancel button set [1] to 3 and [2] to 1.

To disable the Cancel button set [1] to 3 and [2] to 0

record
Required Record object containing a message-specific field.

Return Values

Constant | Value | Description
msiMessageStatusError | -1 | Invalid parameter or handle supplied.
msiMessageStatusNone | 0 | No action taken.
msiMessageStatusOk | 1 | The function succeeded.
msiMessageStatusCancel | 2 | The process was canceled.
msiMessageStatusAbort | 3 | The process was stopped.
msiMessageStatusRetry | 4 | Retry.
msiMessageStatusIgnore | 5 | The process was ignored.
msiMessageStatusYes | 6 | Yes.
msiMessageStatusNo | 7 | No.

Remarks

Message Record Fields

The following describes the record field definitions when msiMessageTypeProgress is passed as the message type.

Field 1 specifies the type of the progress message. The meaning of the other fields depend upon the value in this field. The possible values that can be set into Field 1 are as follows.

Message name | Value | Field 1 description
MasterReset | 0 | Resets progress bar and sets the expected total number of ticks in the bar.
ActionInfo | 1 | Provides information related to progress messages to be sent by the current action.
ProgressReport | 2 | Increments the progress bar.
ProgressAddition | 3 | Enables an action (such as CustomAction) to add ticks to the expected total number of progress of the progress bar.

The meaning of Field 2 depends upon the value in Field 1 as follows.

Field 1 value | Field 2 description
0 | Expected total number of ticks in the progress bar.
1 | Number of ticks the progress bar moves for each ActionData message. This field is ignored if Field 3 is 0.
2 | Number of ticks the progress bar has moved.
3 | Number of ticks to add to total expected progress.

The meaning of Field 3 depends upon the value in Field 1 as follows.

Field 1 value | Field 3 value | Field 3 description
0 | 0 | Forward progress bar (left to right)
 | 1 | Backward progress bar (right to left)
1 | 0 | The current action will send explicit ProgressReport messages.
 | 1 | Increment the progress bar by the number of ticks specified in Field 2 each time an ActionData message is sent.
2 | Unused |
3 | Unused |

The meaning of Field 4 depends upon the value in Field 1 as follows.

Field 1 value | Field 4 value | Field 4 description
0 | 0 | Execution is in progress. In this case, the UI could calculate and display the time remaining.
 | 1 | Creating the execution script. In this case, the UI could display a message to please wait while the installer finishes preparing the installation.
1 | Unused |
2 | Unused |
3 | Unused |


Mode Property

This is the Mode property of the Session object. This property is a value representing the designated mode flag for the current install session. Most of the mode flags are read-only externally, but a few specified flags may be set as well.

The MsiGetMode function returns a Boolean TRUE or FALSE, indicating whether the specific property passed into the function is currently set (TRUE) or not set (FALSE).

Note that not all the run mode values of flag are available when calling the Mode property from a deferred custom action. For more information, see Obtaining Context Information for Deferred Execution Custom Actions.

Syntax

object.Mode(flag)

Parts

object
Session object
flag

Required integer value for the flag. Must be one of the following:

Flag name | Value | Description
msiRunModeAdmin | 0 | Admininstrative mode install, else product install.
msiRunModeAdvertise | 1 | Advertise mode of install.
msiRunModeMaintenance | 2 | Maintenance mode database loaded.
msiRunModeRollbackEnabled | 3 | Rollback is enabled.
msiRunModeLogEnabled | 4 | Log file is active.
msiRunModeOperations | 5 | Executing or spooling operations.
msiRunModeRebootAtEnd | 6 | Reboot is needed (settable).
msiRunModeRebootNow | 7 | Reboot is needed to continue installation (settable).
msiRunModeCabinet | 8 | Installing files from cabinets and files using Media table.
msiRunModeSourceShortNames | 9 | Source files use only short file names.
msiRunModeTargetShortNames | 10 | Target files are to use only short file names.
msiRunModeWindows9x | 12 | Operating system is Windows 95/98, but not Windows NT/Windows 2000.
msiRunModeZawEnabled | 13 | Operating system supports advertising of products.
msiRunModeScheduled | 16 | Deferred custom action called from install script execution.
msiRunModeRollback | 17 | Deferred custom action called from rollback execution script.
msiRunModeCommit | 18 | Deferred custom action called from commit execution script.


ProductProperty Property

The ProductProperty Property of the Session object is a read-only property that retrieves product properties from the product database.

Syntax

object.ProductProperty(name)

Parts

object

Session object

name
Required case-sensitive name of a property.


Property Property (Session Object)

The Property property of the Session object is a read-write property that represents the string value of a named installer property, as maintained by the Session object in the in-memory Property table, or, if it is prefixed with a percent sign (%), the value of a system environment variable for the current process. Either string or integer values may be supplied. A non-existent property or environment variable is equivalent to its value being Null.

Syntax

object.Property(name)

Parts

object
Session object
name
Required case-sensitive name of a property, or a case-insensitive name of an environment variable prefixed by a percent sign (%).


Sequence Method

The Sequence method of the Session object opens a query on the specified table, ordering the actions by the numbers in the Sequence column. For each row fetched, the DoAction method is called, provided that any supplied condition expression does not evaluate to False. Returns an enumeration msiDoActionStatusEnum, as described in the DoAction method.

Syntax

object.Sequence(table)

Parts

object
Session object
table
Required string name of the table to use for sequencing.

Remarks

This method is normally called internally by top-level actions.

An action sequence containing actions that update the system, such as the InstallFiles and WriteRegistryValues actions, cannot be run by calling the Sequence method. The exception to this rule is if the Sequence method is called from a custom action that is scheduled in the InstallExecuteSequence table between the InstallInitialize and InstallFinalize actions. Actions that do not update the system, such as AppSearch or CostInitialize, can be called.


SetInstallLevel Method

The SetInstallLevel method of the Session object sets the install level for the current installation to a specified value and recalculates the Select and Installed states for all features in the Feature table. It also sets the Action state of each component in the Component table based on the new level.

Syntax

object.SetInstallLevel(installLevel)

Parts

object
Session object
installLevel
Required requested new install level.

Remarks

The CostInitialize action must be executed prior to calling SetInstallLevel.

If 0 is passed for the installLevel parameter, the current install level is not changed, but all features are still updated based on the current install level. For example, this functionality could be used by the Handler module to reset all selections back to their initial default states at any point in the UI selection process.


SourcePath Property

The SourcePath property of the Session object is a read-only property that provides the full path to the designated folder on the source media or server image.

Syntax

object.SourcePath(folder)

Parts

object
Session object
folder
Required case-sensitive name of a folder property as specified by a primary key of the Directory table. An error is generated if the folder does not exist.


TargetPath Property

The TargetPath property of the Session object is a read-write property that provides the full path to the designated folder on the installation target drive.

Syntax

object.TargetPath(folder)

Parts

object
Session object
folder
Required case-sensitive name of a folder property as specified by a primary key of the Directory table. An error is generated if the folder does not exist.

Remarks

Do not attempt to configure the target path if the components using those paths are already installed for the current user or for a different user. Check the ProductState property to determine if the product containing the component is installed.


VerifyDiskSpace Property

Syntax

object.VerifyDiskSpace

Parts

object
Session object


Installer Object

An Installer object must be initially created to load the automation support that is required for COM to access the installer functions. This object provides wrappers to create the top-level objects and access their methods.

You can create the Installer object from the ProgId WindowsInstaller.Installer.

Properties

Components
ComponentPath
ComponentQualifiers
Environment
Features
FeatureParent
FeatureState
FeatureUsageCount
Patches
PatchInfo
PatchTransforms
FileAttributes
Products
ProductInfo
ProductState
QualifierDescription
RelatedProducts
SummaryInformation
UILevel
Version

Methods

AddSource
ApplyPatch
ClearSourceList
CollectUserInfo
ConfigureFeature
ConfigureProduct
CreateRecord
EnableLog
FileHash
FileSize
FileVersion
ForceSourceListResolution
GetShortcutTarget
InstallProduct
LastErrorRecord
OpenDatabase
OpenPackage
OpenProduct
ProvideComponent
ProvideQualifiedComponent
RegistryValue
ReinstallFeature
ReinstallProduct
UseFeature

See Also

Using the Automation Interface


AddSource Method

The AddSource method adds a source to the list of valid network sources in the sourcelist.

Syntax

object.AddSource(Product, User, Source)

Parts

object
Installer object
Product
Specifies the product code.
User
User name for per-user installation; NULL or empty string for per-machine installation.
Source
Pointer to the string specifying the source.

Remarks

This property is not available with Windows Installer version 1.0.

See Also

MsiSourceListAddSource, source resiliency


ApplyPatch Method

For each product listed by the patch package as eligible to receive the patch, the ApplyPatch method of the Installer object invokes an installation and sets the PATCH property to the path of the patch package.

Syntax

object.ApplyPatch(PatchPackage, InstallPackage, InstallType, CommandLine)

Parts

object
Installer object
PatchPackage
Specifies a path to the patch package.
InstallPackage
If InstallType is set to msiInstallTypeNetworkImage, InstallPackage specifies the path to the product that is to be patched. If InstallType is set to msiInstallTypeDefault and InstallPackage is set to 0, the installer applies the patch to every eligible product listed in the patch package.
InstallType
This parameter specifies the type of installation to patch. The InstallType parameter is ignored if InstallPackage is omitted.
Value | Type of installation
msiInstallTypeNetworkImage | Indicates a administrative installation. In this case, InstallPackage must be set to a package path. A value of 1 for msiInstallTypeNetworkImage specifies a administrative installation.
msiInstallTypeDefault | Searches system for products to patch. In this case, InstallPackage must be an empty string.

CommandLine
Specifies property settings being set on the command line.

Remarks

Because the list delimiter for transforms, sources, and patches is a semicolon, this character should not be used for file names or paths.

See Also

MsiApplyPatch, About Properties


ClearSourceList Method

The ClearSourceList method removes all network sources from the source list.

Syntax

object.ClearSourceList(Product, User)

Parts

object
Installer object
Product
Specifies the product code.
User
User name for per-user installation; NULL or empty string for per-machine installation.

Remarks

This property is not available with Windows Installer version 1.0.

See Also

MsiSourceListClearAllSee, Source Resiliency


CollectUserInfo Method

The CollectUserInfo method invokes a user interface wizard sequence which collects and stores both user information and the product code.

Syntax

object.CollectUserInfo(Product)

Parts

object
Installer object
Product
Specifies the product code of the product.

Remarks

An application should call the CollectUserInfo method the first time it is run. The CollectUserInfo method opens the product's installation package and invokes an authored user interface wizard sequence which collects user information. Upon completion of the wizard sequence, the collected user information is registered. The UILevel property should be set to msiUILevelFull because this API requires an authored user interface.

The CollectUserInfo method invokes the FirstRun Dialog.

See Also

MsiCollectUserInfo


ComponentPath Property

The ComponentPath property is a read-only property that returns the full path to an installed component. If the key path for the component is a registry key then the registry key is returned.

Syntax

object.ComponentPath (Product, Component)

Parts

object
Installer object
Product
Specifies the product code of the client product.
Component
Specifies the component ID of the component to be located.

Remarks

If the component is a registry key, the registry roots are represented numerically. For example, a registry path of "HKEY_CURRENT_USER\SOFTWARE\Microsoft" would be returned as "01:\SOFTWARE\Microsoft". The registry roots returned are defined as follows:

Root | Returned value
HKEY_CLASSES_ROOT | 00
HKEY_CURRENT_USER | 01
HKEY_LOCAL_MACHINE | 02
HKEY_USERS | 03
HKEY_PERFORMANCE_DATA | 04

See Also

MsiGetComponentPath


ComponentQualifiers Property

The ComponentQualifiers property is a read-only property that returns a StringList object enumerating the set of registered qualifiers for the specified component.

Syntax

object.ComponentQualifiers(Category)

Parts

object
Installer object
Category
A string GUID that represents the category of component.

Remarks

To enumerate qualifiers the application iterates through the StringList object using a For Each construct. Because qualifiers are not ordered, any new qualifier has an arbitrary index, meaning the function can return qualifiers in any order.

See Also

MsiEnumComponentQualifiers


Components Property

The read-only Components property returns a StringList object enumerating the set of installed components for all products.

Syntax

object.Components

Parts

object
Installer object

Remarks

To enumerate the components, an application can iterate through the StringList object using a For Each construct. Because components are not ordered, any new components has an arbitrary index. This means that the function can return components in any order.

See Also

MsiEnumComponents


ConfigureFeature Method

The ConfigureFeature method configures the installed state of a product feature.

Syntax

object.ConfigureFeature(Product, Feature, InstallState)

Parts

object
Installer object
Product
Specifies the product code of the product.
Feature
Specifies the feature ID of the feature to be configured.
InstallState
Specifies the installation state for the feature. This parameter must be one of the following values.
Value | Meaning
msiInstallStateAdvertised | The feature is advertised
msiInstallStateLocal | The feature is installed locally.
msiInstallStateAbsent | The feature is uninstalled.
msiInstallStateSource | The feature is installed to run from source.
msiInstallStateDefault | The feature is installed to its default location.

See Also

MsiConfigureFeature, Installation and Configuration Functions


ConfigureProduct Method

The ConfigureProduct method installs or uninstalls a product.

Syntax

object.ConfigureProduct(Product, InstallLevel, InstallState)

Parts

object
Installer object
Product
Specifies the product code of the product.
InstallLevel
Specifies the default installation configuration of the product. The InstallLevel parameter is ignored and all features are installed if the InstallState parameter is set to any other value than msiInstallStateDefault.

This parameter must be either 0 (install using authored feature levels), 65535 (install all features), or a value between 0 and 65535 to install a subset of available features.

InstallState
Specifies the installation state for the feature. This parameter must be one of the following values.
Value | Meaning
msiInstallStateAdvertised | The feature is advertised
msiInstallStateLocal | The feature is installed locally.
msiInstallStateAbsent | The feature is uninstalled.
msiInstallStateSource | The feature is installed to run from source.
msiInstallStateDefault | The feature is installed to its default location.

Remarks

The ConfigureProduct method displays the user interface using current settings. User interface settings can be changed by modifying the UILevel property (Installer object) before calling the ConfigureProduct method.

If the InstallState parameter is set to any other value than msiInstallStateDefault, the InstallLevel parameter is ignored and all features of the product are installed. Use the ConfigureFeature method to control the installation of individual features when the InstallState parameter is not set to msiInstallStateDefault.

See Also

MsiConfigureProduct, Installation and Configuration Functions


CreateRecord Method

The CreateRecord method of the Installer object returns a new Record object with the requested number of fields.

Syntax

object.CreateRecord(count)

Parts

object
Installer object.
count
Required number of fields, which may be 0. The maximum number of fields in a record is limited to 65535.

Remarks

Field 0, not one of the fields in count, is normally used for record-oriented items such as format strings or execution op-codes.


EnableLog Method

The EnableLog method of the Installer object enables logging of the selected message type for all subsequent install sessions in the current process space.

Syntax

object.EnableLog(logMode, logFile)

Parts

object
Installer object
logMode
Required string containing letters representing the message types to log.
logFile
Required string containing the path to the log file to be created.

Remarks

Log message types | Value | Description
msiMessageTypeInfo | i | Information-only messages
msiMessageTypeWarning | w | Warning messages; not fatal
msiMessageTypeError | e | Error messages; may be fatal
msiMessageTypeFilesInUse | f | List of files in use that need to be replaced
msiMessageTypeActionStart | a | Start of action notification
msiMessageTypeActionData | r | Action data record; contents action-specific
msiMessageTypeUser | u | User request messages
msiMessageTypeCommonData | c | UI initialization parameters
msiMessageTypeOutOfMemory | m | Out-of-memory message
msiMessageTypeVerbose | v | Sends large amounts of information to log file not generally useful to users. May be used for support.
msiMessageTypePropertyDump | p | Dump property table; "property = value" at engine termination
(Any Message Type)+ | (values)+ | Messages overwrite existing log files by default. Include a plus sign to append a message to an existing log file.

See Also

Logging


Environment Property

The Environment property of the Installer object is a read-write property that is the string value for an environment variable or the current process.

Syntax

object.Environment(variable)

Parts

object
Installer object
variable
The name of the environment variable to be read or written. This is case-insensitive.

Remarks

Setting of an environment variable with the Environment property only affects the active session. To make persistent changes to an environment variable, use the Environment table.


FeatureParent Property

The FeatureParent property specifies the parent feature of a feature. An empty string for this property indicates the feature has no parent and is a root item. This is a read-only property.

Syntax

object.FeatureParent(Product, Feature)

Parts

object
Installer object
Product
Specifies the product code of the product.
Feature
Specifies the feature ID of the child feature for which the parent is requested.


Features Property

The Features property is a read-only property that returns a StringList object enumerating the set of published features for the specified product.

Syntax

object.Features(Product)

Parts

object
Installer object
Product
Specifies the product code of the product.

Remarks

To enumerate the features, an application iterates through the StringList object using a For Each construct. Because features are not ordered, any new feature has an arbitrary index, meaning the function can return features in any order.

See Also

MsiEnumFeatures, System Status Functions


FeatureState Property

The read-only FeatureState property returns the installed state of a feature.

Syntax

object.FeatureState(Product, Feature)

Parts

object
Installer object
Product
Specifies the product code of the product that contains the feature.
Feature
Specifies the feature.

Remarks

This property returns one of the following values.

Value | Description
msiInstallStateAbsent | The feature is not installed.
msiInstallStateAdvertised | The feature is advertised.
msiInstallStateLocal | The feature is installed to run locally.
msiInstallStateSource | The feature is installed to run from source.
msiInstallStateInvalidArg | An invalid parameter was passed to the function.
msiInstallStateUnknown | The product code or feature ID is unknown.
msiInstallStateBadConfig | The configuration data is corrupt.

The FeatureState property does not validate that the feature is accessible.

See Also

MsiQueryFeatureState


FeatureUsageCount Property

The FeatureUsageCount property is a read-only property that returns the number of times the feature has been used.

Syntax

object.FeatureUsageCount(Product, Feature)

Parts

object
Installer object
Product
Specifies the product code of the product.
Feature
Identifies the feature of interest.

Remarks

Use of the UseFeature, ProvideComponent or ProvideQualifiedComponent methods or their API equivalents on the specified feature increments this property.

See Also

MsiGetFeatureUsage


FeatureUsageDate Property

The FeatureUsageDate property is a read-only property that returns the date the specified feature was last used.

Syntax

object.FeatureUsageDate(Product, Feature)

Parts

object
Installer object
Product
Specifies the product code of the product.
Feature
Identifies the feature of interest.

Remarks

Use of the UseFeature, ProvideComponent or ProvideQualifiedComponent methods or their API equivalents on the specified feature sets this property.

The date is in the MS-DOS date format as shown in the following table.

Bits | Contents
0-4 | Day of the month (1-31)
5-8 | Month (1 = January, 2 = February, and so on)
9-15 | Year offset from 1980 (add 1980 to get actual year)

See Also

MsiGetFeatureUsage


FileAttributes Property

The FileAttributes property of the Installer object returns a number representing the combined file attributes for the designated path to a file or folder.

Syntax

object.FileAttributes(filePath)

Parts

object
Installer object
filePath
The required path to the file or folder. A partial path assumes the current directory.

Remarks

The FileAttributes property returns the following values.

File attribute | Value | Value
FILE_ATTRIBUTE_READONLY | 0x00000001 | 1
FILE_ATTRIBUTE_HIDDEN | 0x00000002 | 2
FILE_ATTRIBUTE_SYSTEM | 0x00000004 | 4
FILE_ATTRIBUTE_DIRECTORY | 0x00000010 | 16
FILE_ATTRIBUTE_TEMPORARY | 0x00000100 | 256
FILE_ATTRIBUTE_COMPRESSED | 0x00000800 | 2048
FILE_ATTRIBUTE_OFFLINE | 0x00001000 | 4096

Returns -1 if the file or folder does not exist is not accessible.


FileHash Method

[This is preliminary documentation and subject to change.]

The FileHash method of the Installer object takes the path to a file and returns a 128-bit hash of that file. The file hash information is returned as a Record object. The entire 128-bit file hash is returned as four 32-bit IntegerData property fields.

The values returned in the Record object correspond to the four fields of the MSIFILEHASHINFO structure returned by MsiGetFileHash. The numbering of four fields is 1-based. Field 1 corresponds to the HashPart1 column of the MsiFileHash table, field 2 corresponds to the HashPart2 column, field 3 corresponds to the HashPart3 column, and field 4 corresponds to the HashPart4 column.

Syntax

object.FileHash(FilePath, Options)

Parts

object
Installer object
Filepath
Path to the file that is to be hashed.
Options
Reserved for future use. The value of this parameter must be 0.

See Also

MsiFileHash Table, MsiGetFileHash, Default File Versioning.


FileSize Method

The FileSize method of the Installer object uses Win32 API calls to return the size of the file specified in Path.

Syntax

object.FileSize(Path)

Parts

object
Installer object
Path
Required string containing the path to the file.


FileVersion Method

The FileVersion method of the Installer object returns the version string or language string of the path specified in Path using the format that the installer expects to find them in in the database. For versions this is a string in "#.#.#.#" format. For language this is the decimal language ID.

Syntax

object.FileVersion(Path, Language)

Parts

object
Installer object
Path
Required string containing the path to the file.
Language
Flag for designating whether the returned value is a language ID or version string. TRUE returns the language, FALSE returns the version. This parameter is optional, with a default value of FALSE.


ForceSourceListResolution Method

The ForceSourceListResolution method of the Installer object forces the installer to search the source list for a valid product source the next time a source is needed, such as when the installer performs an installation or a reinstallation, or when it needs the path for a component set to run from source.

Syntax

object.ForceSourceListResolution(Product, User)

Parts

object
Installer object
Product
Specifies the product code.
User
User name for per-user installation; NULL or empty string for per-machine installation.

Remarks

This property is not available with Windows Installer version 1.0.

See Also

MsiSourceListForceResolution, Source Resiliency


GetShortcutTarget Method

The GetShortcutTarget method examines a shortcut and returns its product, feature name, and component if available.

Syntax

object.GetShortcutTarget(Shortcut)

Parts

object
Installer object
Shortcut
Full path and file name for the lnk file.

Remarks

This property is not available with Windows Installer version 1.0.

See Also

MsiGetFeatureState, MsiGetComponentState


InstallProduct Method

The InstallProduct method of the Installer object opens an installer package and initializes an install session.

Syntax

object.InstallProduct(packagePath, propertyValues)

Parts

object
Installer object
packagePath
Required string containing the path to the install package.
propertyValues
Optional string containing property=value pairs separated by white space.


LastErrorRecord Method

The LastErrorRecord method of the Installer object returns a Record object containing error parameters for the most recent error from the function that produced the error record.

Syntax

object.LastErrorRecord

Parts

object
Installer object

Remarks

Only the following designated functions generate an error record. The Record object is reset after the execution of this function of any function that generates an error record.

OpenDatabase method (Installer Object)
Commit
OpenView
Import
Export
Merge
GenerateTransform
ApplyTransform
Execute
Modify
SetStream
SummaryInformation
SourcePath
TargetPath
ComponentCurrentState
ComponentRequestState
FeatureCurrentState
FeatureRequestState
FeatureCost
FeatureValidStates
SetInstallLevel


OpenPackage Method

The OpenPackage method of the Installer object opens an installer package for use with function that access the product database and install engine, returning an Session object.

Syntax

object.OpenPackage packagePath

Parts

object
Installer object
packagePath
Required string containing the path name of the package.

Remarks

The OpenPackage method can accept the database handle directly instead of the string for the package path.

Note that only one Session object can be opened by a single process. OpenPackage cannot be used in a custom action because the active installation is the only session allowed.


OpenDatabase Method (Installer Object)

The OpenDatabase method of the Installer object opens an existing database or creates a new one, returning a Database object. It generates an error if the Database object cannot be successfully created and opened.

Syntax

object.OpenDatabase(name, openMode)

Parts

object
Installer object
name
Required string containing the path name of the database. If an empty string is supplied, a temporary database is created that is not persisted.
openMode
A parameter from the following list or a string containing the path name of the new output database file that is to be written to upon commit.
Parameter name | Value | Description
msiOpenDatabaseModeReadOnly | 0 | Open a database read-only, no persistent changes.
msiOpenDatabaseModeTransact | 1 | Open a database read/write in transaction mode.
msiOpenDatabaseModeDirect | 2 | Open a database direct read/write without transaction.
msiOpenDatabaseModeCreate | 3 | Create a new database, transact mode read/write.
msiOpenDatabaseModeCreateDirect | 4 | Create a new database, direct mode read/write.
msiOpenDatabaseModePatchFile | 32 | Add this flag to indicate a patch file.

Remarks

When a database is opened as the output of another database, the summary information stream of the output database is actually a read-only mirror of the original database and thus cannot be changed. Additionally, it is not persisted with the database. To create or modify the summary information for the output database it must be closed and re-opened.

To make and save changes to a database first open the database in transaction (msiOpenDatabaseModeTransact), create (msiOpenDatabaseModeCreate or msiOpenDatabaseModeCreateDirect), or direct (msiOpenDatabaseModeDirect) mode. After making the changes, always call the Commit method before closing the database handle. The Commit method flushes all buffers.

Always call the Commit method on a database that has been opened in direct mode (msiOpenDatabaseModeDirect or msiOpenDatabaseModeCreateDirect) before closing the database. Failure to do this may corrupt the database.

Because the OpenDatabase method initiates database access, it cannot be used with a running installation


OpenProduct Method

The OpenProduct method of the Installer object opens an installer package for an installed product using the product code and returns a Session object.

Syntax

object.OpenProduct productCode

Parts

object
Installer object
productCode
Required string containing the unique product code (a GUID) or an activation descriptor written by the installer.

Remarks

Note that only one Session object can be opened by a single process. OpenProduct cannot be used in a custom action because the active installation is the only session allowed.


Patches Property

The read-only Patches property of the Installer object returns a StringList object that contains all the patches applied to the product.

Syntax

object.Patches(Product)

Parts

object
Installer object
Product
Specifies the product code.

Remarks

To enumerate the patches, an application iterates through the StringList object using a For Each construct. Because patches are not ordered, any new patch has an arbitrary index. This means that the function can return patches in any order.

This property is not available with Windows Installer version 1.0.

See Also

MsiEnumPatches


PatchInfo Property

The read-only PatchInfo property of the Installer object returns information about a patch.

Syntax

object.PatchInfo(Patch, Attribute)

Parts

object
Installer object
Patch
Specifies the patch code for the patch package.
Attribute
Specifies the the attribute to be retrieved.

Remarks

This property is not available with Windows Installer version 1.0.

See Also

MsiGetPatchInfo


PatchTransforms Property

The read-only PatchTransforms property returns the semi-colon delimited list of transforms that are in the specified patch package and applied to the specified product.

Syntax

object.PatchTransforms(Product, Patch)

Parts

object
Installer object
Product
Specifies the product code.
Patch
Specifies the patch code.

Remarks

This property is not available with Windows Installer version 1.0.

See Also

MsiEnumPatches


ProductInfo Property

The ProductInfo property is a read-only property that returns the value of the specified attribute for an installed or published product.

Syntax

object.ProductInfo(Product, Attribute)

Parts

object
Installer object
Product
Specifies the product code of the installed product that contains the attribute of interest.
Attribute
Identifies the attribute to be retrieved. The properties in the following list can only be retrieved from applications that are installed.
Property name | Description
InstalledProductName | Installed product name. See ProductName property.
VersionString | Product version. See ProductVersion property.
HelpLink | Support link. See ARPHELPLINK property.
HelpTelephone | Support telephone. See ARPHELPTELEPHONE property.
InstallLocation | Installation location. See ARPINSTALLLOCATION property.
InstallSource | Installation source. See SourceDir property.
InstallDate | Installation date.
Publisher | Publisher. See Manufacturer property.
LocalPackage | Local cached package
URLInfoAbout | URL information. See ARPURLINFOABOUT property.
URLUpdateInfo | URL update information. See ARPURLUPDATEINFO property.
VersionMinor | Minor product version derived from ProductVersion property.
VersionMajor | Major product version derived from ProductVersion property.

The attributes in the following list can be retrieved from applications that are advertised.
Property Name | Description
Transforms | Transforms
Language | Product language
ProductName | Human readable product name. See ProductName property.
AssignmentType | Assignment type
AdvertiseFlags | Advertisement flags.
PackageCode | Identifier of package product was installed from. See Package Codes.
Version Product

version derived from ProductVersion property.
ProductIcon | Primary Icon for the package. See ARPPRODUCTICON property.

Remarks

ProductInfo("LocalPackage") does not necessarily return a path to the cached package. Maintenance mode installations should be not be invoked from the LocalPackage. The cached package is for internal uses only.

See Also

MsiGetProductInfo, MsiGetUserInfo


Products Property

The Products property is a read-only property that returns a StringList object enumerating the set of all products installed or advertised for the current user and machine.

Syntax

object.Products

Parts

object
Installer object

Remarks

To enumerate the products, an application iterates through the StringList object using a For Each construct. Because products are not ordered, any new product has an arbitrary index. This means that the function can return products in any order.

See Also

MsiEnumProducts


ProductState Property (Installer object)

The ProductState property is a read-only property that returns the install state information for a product.

Syntax

object.ProductState(Product)

Parts

object
Installer object
Product
Specifies the product code of the product.

Remarks

Returns one of the following values.

Installation state | Description
msiInstallStateAbsent | The product is installed for a different user.
msiInstallStateDefault | The product is installed for the current user.
msiInstallStateAdvertised | The product is advertised but not installed.
msiInstallStateInvalidArg | An invalid parameter was passed to the function.
msiInstallStateUnknown | The product is neither advertised nor installed.
msiInstallStateBadConfig | The configuration data is corrupt.

See Also

MsiQueryProductState


ProvideComponent Method

The ProvideComponent method returns the full component path and performs any necessary installation. If necessary, the ProvideComponent method prompts for the source and increments the usage count for the feature.

Syntax

object.ProvideComponent(Product, Feature, Component, InstallMode)

Parts

object
Installer object
Product
Specifies the product code of the product.
Feature
Specifies the feature ID of the feature containing the component.
Component
Specifies the component code.
InstallMode
Defines the installation mode. This parameter can be one of the following values.
Name | Value | Meaning
msiInstallModeDefault | 0 | Provide the component path, performing any installation if necessary.
msiInstallModeExisting | -1 | Provide the component path only if the feature exists. Otherwise, return an empty string. This mode verifies the existence of the component's key file.
msiInstallModeNoDetection | -2 | Provide the component path only if the feature exists. Otherwise, return an empty string. This mode checks the component's registration and does not verify the existence of the component's key file.
msiInstallModeNoSourceResolution | -3 | Provide the component path only if the feature exists with an InstallState parameter of msiInstallStateLocal. This checks the component's registration and does not verify the existence of the component's key file.
combination of the msiReinstallMode flags | Call ReinstallFeature to reinstall the feature using this parameter for the ReinstallMode parameter, and then provide the component.

Remarks

The ProvideComponent method combines the functionality of UseFeature, ConfigureFeature, and ComponentPath. The ProvideComponent method simplifies the calling sequence, but it also increments the usage count and should be used with caution to prevent inaccurate usage counts. The ProvideComponent method also provides less flexibility than a series of individual calls to the methods and properties previously mentioned.

If the application is recovering from an unexpected situation, the application has probably already called UseFeature and incremented the usage count. In this case, the application should avoid incrementing the usage count by calling the ConfigureFeature method instead of the ProvideComponent method.

The msiInstallModeExisting option cannot be used in combination with msiReinstallMode flags

See Also

MsiProvideComponent


ProvideQualifiedComponent Method

The ProvideQualifiedComponent method returns the full component path and performs any necessary installation. If necessary, this method prompts for the source and increments the usage count for the feature.

Syntax

object.ProvideQualifiedComponent(Category, Qualifier, InstallMode)

Parts

object
Installer object
Category
Specifies the component ID that for the requested component. This may not be the GUID for the component itself but rather a server that provides the correct functionality, as in the ComponentId column of the PublishComponent table.
Qualifier
Specifies a qualifier into a list of advertising components (from PublishComponent table).
InstallMode
Defines the installation mode. This parameter can be one of the following values.
InstallMode | Value | Meaning
msiInstallModeDefault | 0 | Provide the component, performing any necessary installation.
msiInstallModeExisting | -1 | Provide the component only if the feature exists. Otherwise return an empty string. This mode verifies the existence of the component's key file.
msiInstallModeNoDetection | -2 | Provide the component only if the feature exists. Otherwise return an empty string. This mode only checks that the component is registered and does not verify the existence of the component's key file.
msiInstallModeNoSourceResolution | -3 | Provide the component path only if the feature exists with an InstallState parameter of msiInstallStateLocal. This checks the component's registration and does not verify the existence of the component's key file.
combination of the msiReinstallMode flags | Call ReinstallFeature to reinstall the feature using this parameter for the ReinstallMode parameter, and then provide the component.

See Also

MsiProvideQualifiedComponent


QualifierDescription Property

The read-only QualifierDescription property returns a text string describing the qualified component. This localizable string is authored into the AppData column of the PublishComponent table and can be displayed to the user. The qualifier distinguishes multiple forms of the same component, such as a component that is implemented in multiple languages.

Syntax

object. QualifierDescription(Category, Qualifier)

Parts

object
Installer object
Category
A string GUID that represents the category of a qualified component. See Qualified Components.
Qualifier
The needed registered qualifier.

See Also

MsiEnumComponentQualifiers, Qualified Components


RegistryValue Method

The RegistryValue method of the Installer object reads information about a specified registry key of value. If the key or value specified does not exist, the method returns an error of 9, "Subscript out of Range."

Syntax

object.RegistryValue(root, key, value)

Parts

object
Installer object
root
In Microsoft® Windows NT® Version 4.0, the registry root is either a numeric root key or a machine name as a string. Machine names are always strings. In Windows 95 or Windows 98, the registry root is a numeric root key only. You can only access HKLM on a remote machine.
Root | Value
HKEY_CLASSES_ROOT | 0
HKEY_CURRENT_USER | 1
HKEY_LOCAL_MACHINE | 2
HKEY_USERS | 3
HKEY_PERFORMANCE_DATA | 4
HKEY_CURRENT_CONFIG | 5
HKEY_DYN_DATA | 6

key
A string containing the complete key path from the root. On Windows 95 or Windows 98, registry key class names are not supported and can not be used.
value
This optional parameter designates which associated value to return for the specified key. The value is one of the following:
Value | Description
Missing or blank | Returns a Boolean designating whether the key exists.
String | Returns the data associated with the named value, fails if the value name is non-existent.
Positive integer | Returns the 1-based enumerated value name, it is empty if non-existent.
Negative integer | Returns the 1-based enumerated subkey name, this is empty if non-existent.
Zero integer | Returns the string class name for the designated key.
Empty string " " | Returns the default value of registry key.


ReinstallFeature Method

The ReinstallFeature method reinstalls features or corrects problems with installed features.

Syntax

object.ReinstallFeature Product, Feature, ReinstallMode

Parts

object
Installer object
Product
Specifies the product code of the product.
Feature
Identifies the feature to be reinstalled.
ReinstallMode
Specifies the type of reinstallation. This parameter can be one or more of the following values.
Value | Meaning
msiReinstallModeFileMissing | Reinstall only if the file is missing.
msiReinstallModeFileOlderVersion | Reinstall if the file is missing or is an older version.
msiReinstallModeFileEqualVersion | Reinstall if the file is missing or is an equal or older version.
msiReinstallModeFileExact | Reinstall if the file is missing or is not an exact version.
msiReinstallModeFileVerify | Check sum executables, and reinstall if they are missing or corrupt.
msiReinstallModeFileReplace | Reinstall all files regardless of version.
msiReinstallModeUserData | Ensure required per-user registry entries.
msiReinstallModeMachineData | Ensure required per-machine registry entries.
msiReinstallModeShortcut | Validate shortcuts.
msiReinstallModePackage | Use the re-cache source to install the package.

See Also

MsiReinstallFeature, Installation and Configuration Functions


ReinstallProduct Method

The ReinstallProduct method reinstalls a product or corrects installation problems in an installed product.

Syntax

object.ReinstallProduct Product, ReinstallMode

Parts

object
Installer object
Product
Specifies the product code of the product.
ReinstallMode
Specifies the type of reinstallation. This parameter can be one or more of the following values.
Value | Meaning
msiReinstallModeFileMissing | Reinstall only if the file is missing.
msiReinstallModeFileOlderVersion | Reinstall if the file is missing or is an older version.
msiReinstallModeFileEqualVersion | Reinstall if the file is missing or is an equal or older version.
msiReinstallModeFileExact | Reinstall if the file is missing or is not an exact version.
msiReinstallModeFileVerify | Check sum executables, and reinstall if they are missing or corrupt.
msiReinstallModeFileReplace | Reinstall all files regardless of version.
msiReinstallModeUserData | Ensure required per-user registry entries.
msiReinstallModeMachineData | Ensure required per-machine registry entries.
msiReinstallModeShortcut | Validate shortcuts.
msiReinstallModePackage | Use the re-cache source to install the package.

See Also

MsiReinstallProduct, Installation and Configuration Functions


RelatedProducts Property

The read-only RelatedProducts property returns a StringList object enumerating the set of all products installed or advertised for the current user and machine with a specified UpgradeCode property in their Property table.

Syntax

object.RelatedProducts(UpgradeCode)

Parts

object
Installer object
UpgradeCode
The upgrade code of related products that the installer enumerates.

Remarks

To enumerate the related products, an application iterates through the StringList using a For Each construct. Because related products are not ordered, any new related product has an arbitrary index. This means that the function can return related products in any order.

This property is not available with Windows Installer version 1.0.

See Also

MsiEnumRelatedProducts


SummaryInformation Property (Installer Object)

The SummaryInformation property of the Installer object returns a SummaryInfo object that can be used to examine, update, and add properties to the summary information stream of a package or transform.

Syntax

object.SummaryInformation(packagePath, maxProperties)

Parts

object
Installer object.
packagePath
Required full path to the package (database) or transform.
maxProperties
Required maximum number of properties to be added or modified. Used solely to allocate sufficient working memory during the stream generation. It is not required to actually store this number of properties. A value of zero prevents the stream from being updated and must be used if the database is opened as read-only.

Remarks

If a value of maxProperties greater than 0 is used to open an existing summary information stream, the Persist method must be called before closing the object. Failing to do this loses the existing stream information.


UILevel Property (Installer object)

The UILevel property of the Installer object is a read-write property that indicates the type of user interface to be used when opening and processing subsequent packages within the current process space.

Syntax

object.UILevel

Parts

object
Installer object.

Remarks

User interface level | Value | Description
msiUILevelNoChange | 0 | Does not change UI level.
msiUILevelDefault | 1 | Uses Default UI level.
msiUILevelNone | 2 | Silent installation.
msiUILevelBasic | 3 | Simple progress and error handling.
msiUILevelReduced | 4 | Authored UI, wizard dialogs suppressed.
msiUILevelFull | 5 | Authored UI with wizards, progress, and errors.
msiUILevelEndDialog | 6 | If combined with any above value, the installer displays a modal dialog box at the end of a successful installation or if there has been an error. No dialog box is displayed if the user cancels.
msiUILevelProgressOnly | 64 | If combined with the msiUILevelBasic value, the installer displays progress dialog boxes but does not display any modal dialog boxes or error dialog boxes.


UseFeature Method

The UseFeature method increments the usage count for a particular feature and returns the installation state for that feature. This method should be used to indicate an application's intent to use a feature.

Syntax

object.UseFeature (Product, Feature, InstallMode)

Parts

object
Installer object
Product
Specifies the product code of the product.
Feature
Identifies the feature to be used.
InstallMode
This parameter must be msiInstallModeNoDetection.

Remarks

The UseFeature method should only be used on features known to be published. The application should determine the status of the feature by calling either the FeatureState property or Features property or their API equivalents.

See Also

MsiUseFeatureEx


Version Property (Installer Object)

The Version property of the Installer object is a read-only property that is the string representation of the current version of the installer. The string is returned in the following form.

major.minor.build.update

Syntax

object.Version

Parts

object
Installer object


Record Object

The Record object is a container for holding and transferring a variable number of values. Fields within the record are numerically indexed and can contain strings, integers, objects, and Null values. Fields beyond the allocated record size are treated as having permanently Null values. Field number 0 is reserved.

Properties

DataSize
FieldCount
IntegerData
IsNull
StringData

Methods

ClearData
FormatText
ReadStream
SetStream

See Also

CreateRecord Method


ClearData Method

The ClearData method of the Record object clears the data in all fields, setting them to Null. Any objects stored in the fields are released.

Syntax

object.ClearData

Parts

object
Record object


DataSize Property

The DataSize property of the Record object is a read-only property that returns the size of the data for the designated field. If the data is a stream, the stream length in bytes is returned. If the data is a string, the string length without Null is returned. If the data is an integer, the value 4 is returned (indicating the size of the integer). If the data is Null, 0 is returned.

Syntax

object.DataSize(field)

Parts

object
Record object
field
Required field number of the value within the record, 1-based.


FieldCount Property

The FieldCount property of the Record object is a read-only property that returns the number of fields in the record. Read access to fields beyond this count returns Null values. Write access fails.

Syntax

object.FieldCount

Parts

object
Record object


FormatText Method

The FormatText method of the Record object formats fields according to the template in field 0.

Syntax

object.FormatText

Parts

object
Record object

Remarks

The FormatText method follows the functionality of the MsiFormatRecord function if MsiFormatRecord was passed a NULL installer handle as its first parameter. As a result, only the record field parameters are processed and properties are not available for substitution.

For example, a string such as "format this field: [1], format this property: [property]" is resolved to "format this field: value from field 1, format this property: [property]."

Parameters that are to be formatted are enclosed in square brackets [...]. The square brackets can be iterated because the substitutions are resolved from the inside out.

If a part of the string is enclosed in curly braces { } and contains no square brackets, it is left unchanged, including the curly braces.

See Also

MsiFormatRecord, Formatted, Column Data Types


IntegerData Property

This is the IntegerData property of the Record object. This read-write property transfers 32-bit integer data in to or out of a specified field within the record. If a field value cannot be converted to an integer, msiDatabaseNullInteger is returned.

Syntax

object.IntegerData(field)

Parts

object
Record object
field
Required field number of the value within the record, 1-based.

Remarks

To set a record integer field to NULL, use msiDatabaseNullInteger. The returned value of a non-existent field is msiDatabaseNullInteger. Attempting to store a value in a non-existent field causes an error.


IsNull Property

The IsNull property of the Record object is a read-only property that returns True if the indicated field is Null and False if the field contains data.

Syntax

object.IsNull(field)

Parts

object
Record object
field
Required field number of the value within the record, 1-based.


ReadStream Method

The ReadStream method of the Record object reads a specified number of bytes from a record field holding stream data.

Syntax

object.ReadStream(field, length, format)

Parts

object
Record object
field
Required field number of the value within the record, 1-based.
length
Required number of bytes to read from the stream.
format
Required interpretation and return of the data bytes, one of the following:
Parameter name | Value | Description
msiReadStreamInteger | 0 | As a long integer, length must be 1 to 4.
msiReadStreamBytes | 1 | Data as a BSTR; one byte per character.
msiReadStreamAnsi | 2 | ANSI bytes translated to a Unicode BSTR.
msiReadStreamDirect | 3 | Byte pairs returned directly as a BSTR.

Remarks

The returned value of a non-existent field is an Empty value. If the stream has fewer bytes that the count requested, the returned string is shortened appropriately.


SetStream Method

The SetStream method of the Record object copies the content of the specified file into the designated record field as stream data. Stream data cannot be inserted into temporary fields.

Syntax

object.SetStream(field, filePath)

Parts

object
Record object
field
Required field number of the value within the record, 1-based.
filePath
The location of the file to copy. No translation of any type is performed.


StringData Property

The StringData property of the Record object is a read-write property that transfers string data in to or out of a specified field within the record. If an integer or object has been stored, its string value is returned.

Syntax

object.StringData(field)

Parts

object
Record object
field
Required field number of the value within the record, 1-based.

Remarks

The returned value of a non-existent field is an empty string. To set a record string field to NULL, use either an Empty variant or an empty string. Attempting to store a value in a non-existent field causes an error.


SummaryInfo Object

The SummaryInfo object is used to read, create, and update document properties from the summary information stream of a storage object.

Properties

Property Property (SummaryInfo Object)
PropertyCount

Methods

Persist

See Also

SummaryInformation Property (Database Object), SummaryInformation Property (Installer Object).


Persist Method

The Persist method of the SummaryInfo object formats and writes the previously stored properties into the standard SummaryInformation stream. It generates an error if the stream cannot be successfully written. This method may only be called once after all the property values have been set. Properties may still be read after the stream is written.

Syntax

object.Persist

Parts

object
SummaryInfo object


Property Property (SummaryInfo Object)

The Property property of the SummaryInfo object sets or gets the value for the specified property in the summary information stream. The properties are read when the SummaryInfo object is created, but they are not written until the Persist method is called. Setting a property to Empty causes its removal; likewise, requesting a non-existent property returns an Empty value. Otherwise values may be transferred as strings, integers, or date (date time) types.

Syntax

object.Property(pid)

Parts

object
SummaryInfo object
pid
Required property ID of one of the summary properties.

Remarks

Standard Summary Property IDs

(not an enumeration)

Parameter name | Value | Description
PID_DICTIONARY | 0 | Special format, not support by SummaryInfo object
PID_CODEPAGE | 1 | VT_I2
PID_TITLE | 2 | VT_LPSTR
PID_SUBJECT | 3 | VT_LPSTR
PID_AUTHOR | 4 | VT_LPSTR
PID_KEYWORDS | 5 | VT_LPSTR
PID_COMMENTS | 6 | VT_LPSTR
PID_TEMPLATE | 7 | VT_LPSTR
PID_LASTAUTHOR | 8 | VT_LPSTR
PID_REVNUMBER | 9 | VT_LPSTR
PID_EDITTIME | 10 | VT_FILETIME
PID_LASTPRINTED | 11 | VT_FILETIME
PID_CREATE_DTM | 12 | VT_FILETIME
PID_LASTSAVE_DTM | 13 | VT_FILETIME
PID_PAGECOUNT | 14 | VT_I4
PID_WORDCOUNT | 15 | VT_I4
PID_CHARCOUNT | 16 | VT_I4
PID_THUMBNAIL | 17 | VT_CF (not supported)
PID_APPNAME | 18 | VT_LPSTR
PID_SECURITY | 19 | VT_I4

Property Data Types

(not an enumeration)

Parameter name | Value | Description
VT_I2 | 2 |  | 16-bit integer
VT_I4 | 3 |  | 32-bit integer
VT_LPSTR | 30 |  | String
VT_FILETIME | 64 |  | Date time (FILETIME, converted to Variant time)
VT_CF | 71 |  | Clipboard format + data, not handled by SummaryInfo object


PropertyCount Property

The PropertyCount property of the SummaryInfo object is a read-only property that indicates the current number of property values in the summary information object. It takes into account properties that have been added, deleted, or replaced.

Syntax

object.PropertyCount

Parts

object
SummaryInfo object


UIPreview Object

The UIPreview object is used to view user interface dialog boxes and billboards during authoring. This object is created by the EnableUIPreview method of the Database object.

Properties

Property Property (UIPreview Object)

Methods

ViewBillboard
ViewDialog


Property Property (UIPreview Object)

The Property property of the UIPreview object is a read-write property that represents the string value of a named installer property, or, if it is prefixed with a percent sign (%), the value of a system environment variable for the current process. This is exposed to allow proper display of dialog boxes that are dependent upon property values. Either string or integer values may be supplied. A non-existent property or environment variable is equivalent to its value being Null.

Syntax

object.Property(name)

Parts

object
UIPreview object
name
Required case-sensitive name of a property, or a case-insensitive name of an environment variable prefixed by a percent sign (%).


ViewBillboard Method

The ViewBillboard method of the UIPreview object displays an authored billboard using the host control in the currently displayed dialog box.

Syntax

object.ViewBillboard(control, billboard)

Parts

object
UIPreview object
control
Required name of the control hosting the billboard, case-sensitive, along with the dialog box, and the primary keys of the Control database table.
billboard
Required name of the billboard to display using the specified control and current dialog box, and the primary key of the Billboard database table.


ViewDialog Method

The ViewDialog method of the UIPreview object displays an authored user interface dialog box stored in the current database.

Syntax

object.ViewDialog(dialog)

Parts

object
UIPreview object
dialog
Required name of the dialog box, case-sensitive, and the primary key of the Dialog database table.


View Object

The View object represents a result set obtained when processing a query using the OpenView method of the Database object. Before any data can be transferred, the query must be executed using the Execute method, passing to it all replaceable parameters designated within the SQL query string. The query may be executed again, with different parameters if needed, but only after freeing the result set either by fetching all the records or by calling the Close method.

Properties

ColumnInfo

Methods

Close
Execute
Fetch
GetError
Modify


Close Method

The Close method of the View object terminates query execution and releases database resources.

Syntax

object.Close

Parts

object
View object

Remarks

This method must be called before the Execute method is called again on the View object unless all rows of the result set have been obtained with the Fetch method. It is called internally when the view is destroyed.


ColumnInfo Property

The ColumnInfo property of the View object returns an Record object containing the requested information about each column in the result set. Either the column names or the column definitions may be requested. Constants supplied in the Select list do not have names.

Syntax

object.ColumnInfo(info)

Parts

object
View object
info
Required information needed for each column:
Parameter name | Value | Description
msiColumnInfoNames | 0 | Return names of all non-constant columns in result set.
msiColumnInfoTypes | 1 | Return types of all non-constant columns in result set.

Remarks

The column descriptions returned by the ColumnInfo property are in the format described in Column Definition Format. Each column is described by a string in the corresponding record field. The definition string consists of a single letter representing the data type followed by the width of the column (in characters when applicable, or else bytes). A width of zero designates an unbounded width (long text fields and streams). An uppercase letter indicates that Null values are allowed in the column.


Execute Method

The Execute method of the View object uses the question mark token to represent parameters in a SQL. For more information, see SQL Syntax. The values of these parameters are passed in as the corresponding fields of a parameter record.

Syntax

object.Execute record

Parts

object
View object
record
Optional Record objects containing the values that replace the parameter tokens (?) in the SQL query.

Remarks

This method must be called before any calls to the Fetch method.

If the SQL query specifies values with parameter markers (?), a record must be supplied containing all of the replacement values, which must be in the same order and of the same data type as the parameter markers. When this method is used with INSERT and UPDATE queries, the question mark tokens must precede all the non-parameterized values.

For example, these queries are valid.

UPDATE {table-list} SET {column}= ? , {column}= {constant}

INSERT INTO {table} ({column-list}) VALUES (?, {constant-list})

However these queries are invalid.

UPDATE {table-list} SET {column}= {constant}, {column}=?

INSERT INTO {table} ({column-list}) VALUES ({constant-list}, ? )


Fetch Method

The Fetch method of the View object returns a Record object containing the requested column data if more rows are available in the result set, else returns Null.

Syntax

object.Fetch

Parts

object
View object

Remarks

This method must be called after the Execute method. For maximum performance, the same Record object should be used for all fetches, or else it should be released by going out of scope. The returned record can be tested for the end of the result set using the syntax "If FetchRecord Is Nothing".


GetError Method

The GetError method of the View object returns the Validation error and the column name for which the error occurred. In automation, the returned value is a string of the form ##ColumnName, where the ## represents a 2-digit error code. It returns the first error in the view's error array; subsequent calls return the next value in the error array. Once a value of '00' is returned, no more errors exist, and subsequent calls merely loop through the array again.

Syntax

object.GetError

Parts

object
View object


Modify Method

The Modify method of the View object modifies a database row with a modified Record object obtained by the Fetch method.

Syntax

object.Modify(action, record)

Parts

object
View object
action
Required action to be performed on the database row. This action is one of the following:
Action name | Value | Description
msiViewModifySeek | -1 | Refreshes the information in the supplied record without changing the position in the result set and without affecting subsequent fetch operations. The record may then be used for subsequent Update, Delete, and Refresh. All primary key columns of the table must be in the query and the record must have at least as many fields as the query.Seek cannot be used with multi-table queries. See also the remarks. This mode cannot be used with a view containing joins.
msiViewModifyRefresh | 0 | Refreshes the information in the record. Must first call Fetch method with the same record. Fails for a deleted row. Works with both read-write and read-only records.
msiViewModifyInsert | 1 | Inserts a record. Fails if a row with the same primary keys exists. Fails with a read-only database. This mode cannot be used with a view containing joins.
msiViewModifyUpdate | 2 | Updates an existing record. Non-primary keys only. Must first call Fetch method with the same record. Fails with a deleted record. Works only with read-write records.
msiViewModifyAssign | 3 | Writes current data in the cursor to a table row. Updates record if the primary keys match an existing row and inserts if they do not match. Fails with a read-only database. This mode cannot be used with a view containing joins.
msiViewModifyReplace | 4 | Updates or deletes and inserts a record into a table. Must first call Fetch method with the same record. Updates record if the primary keys are unchanged. Deletes old row and inserts new if primary keys have changed. Fails with a read-only database. This mode cannot be used with a view containing joins.
msiViewModifyMerge | 5 | Inserts or validates a record in a table. Inserts if primary keys do not match any row and validates if there is a match. Fails if the record does not match the data in the table. Fails if there is a record with a duplicate key that is not identical. Works only with read-write records. This mode cannot be used with a view containing joins.
msiViewModifyDelete | 6 | Remove a row from the table. Must first call Fetch method with the same record. Fails if the row has been deleted. Works only with read-write records. This mode cannot be used with a view containing joins.
msiViewModifyInsertTemporary | 7 | Inserts a temporary record. The information is not persistent. Fails if a row with the same primary key exists. Works only with read-write records. This mode cannot be used with a view containing joins.
msiViewModifyValidate | 8 | Validates a record. Does not validate across joins. Must first call Fetch method with the same record. Obtain validation errors with GetError method. Works with read-write and read-only records. This mode cannot be used with a view containing joins.
msiViewModifyValidateNew | 9 | Validate a new record. Does not validate across joins. Checks for duplicate keys. Obtain validation errors by calling GetError method. Requires calling MsiDatabase.OpenView method with a modify value. Works with read-write and read-only records. This mode cannot be used with a view containing joins.
msiViewModifyValidateField | 10 | Validates fields of a fetched or new record. Can validate one or more fields of an incomplete record. Obtain validation errors by calling GetError method. Works with read-write and read-only records. This mode cannot be used with a view containing joins.
msiViewModifyValidateDelete | 11 | Validates a record that will be deleted later. Must first call Fetch method with the same record. Fails if another row refers to the primary keys of this row. Validation does not check for the existence of the primary keys of this row in properties or strings. Does not check if a column is a foreign key to multiple tables. Obtain validation errors by calling GetError method. Works with read-write and read-only records. This mode cannot be used with a view containing joins.

record
Required. Record object obtained by the Fetch method with modified field data.

Remarks

This method must be called after the Execute method.

To execute any SQL statement, a view must be created. However, a view that does not create a result set, such as CREATE TABLE, or INSERT INTO, cannot be used with the Modify method to update tables though the view.

The msiViewModifyValidate, msiViewModifyValidateNew, msiViewModifyValidateField, and msiViewModifyValidateDelete values of the Modify method do not perform actual updates; they ensure that the data in the record is valid. Use of these actions requires that the database contain a _Validation table .

You cannot fetch a record containing binary data from one database and then use that record to insert the data into a completely different database. To move binary data from one database to another, you should export the data to a file and then import it into the new database using the SetStream method of the Record Object. This ensures that each database has its own copy of the binary data.

Note that custom actions can only add, modify, or remove temporary rows, columns, or tables from a database. Custom actions cannot modify persistent data in a database, such as data that is a part of the database stored on disk. For more information, see How do I access the current installer session from inside a custom action?


StringList Object

The StringList object is a collection of strings. The client must verify that the StringList object exists and is not empty before referencing its properties.

Properties

Count

Item


Count Property

The Count property is a read-only property that returns the number of items in the StringList Object.

Syntax

object.Count

Parts

object
StringList Object

Remarks

The client must verify that the StringList object exists and is not empty before referencing the Count property.


Item Property

The Item property is a read-only property that returns a string in the StringList Object collection.

Syntax

object.Item(Index)

Parts

object
StringList Object
Index
Index number of the item with the collection of strings. Index is required.

Remarks

The client must verify that the StringList object exists and is not empty before referencing the Item property.


Patching and Upgrades

This section describes the methods Microsoft® Windows® Installer uses for updating an application. Because an installation package contains all the information needed for an installation, as well as the files that make up the application, information can be updated within the following parts of the installation package:

  • The .msi file.
  • The files of the application.
  • The Windows Installer registration information.

If the update changes the .msi file as well as application files, without changing the product code or product version, it is termed a Small Update.

If the update changes the product version, but does not change the product code, it is termed a Minor Upgrade. The product version is stored in the ProductVersion property.

If the update changes the installation into an entirely different product the product code must change and the update is a Major Upgrade. The product code is stored in the ProductCode property.

The following table summarizes the different types of updates.

Type of update | ProductCode | ProductVersion | Description
Small Update | No change | No change | An update to one or two files that is too small to warrant changing the ProductVersion. The package code in the Revision Number Summary Property does change. Can be shipped as a full installation package or as a patch package.
Minor Upgrade | No change | Changed | A small update making changes large enough to warrant changing the ProductVersion property. Can be shipped as a full installation package or as a patch package.
Major Upgrades | Changed | Changed | A comprehensive update of the product warranting a change in the ProductCode property. Shipped as a patch package or as a full product installation package.

The package code uniquely identifies an installation package and should change whenever an update or upgrade changes the installation package. See Package Codes.

When deciding whether to change the product version, you should consider if future versions of the application will need to differentiate between the updated, and non-updated versions of the current product. To ensure differentiation in the future a Minor Upgrade should be used instead of a Small Update.

A Windows Installer patch package is one means of providing users with an application update. A patch can contain an entire file or only the file bits necessary to update part of a file. This means that the user can download an upgrade patch that is much smaller than the entire product and that preserves user customizations through the upgrade. For more information about updating an application using a patch, see Patch Packages and Creating a Patch Package.


Small Updates

A small update makes changes to one or more application files that are judged to be too minor to warrant changing the product code. Because a small update changes the information in the .msi file, the installation package code must be changed. The package code is stored in the Revision Number Summary Property of the Summary Information Stream.

The product code is never changed with a small update, so all of the changes introduced by a small update have to be consistent with the guidelines described in Changing the Product Code. If it is necessary to differentiate between products without changing the product code, use a Minor Upgrade.

For information on how to apply a small update patch package to a Windows Installer package, see Small Updates by Patching the Local Installation of the Product, Small Updates by Reinstalling the Product, and Small Updates by Patching an Administrative Image.


Small Updates by Patching the Local Installation of the Product

A small update can be applied to an application by patching the local installation of the application.

To apply a Small Update patch to a local installation of the product

  1. Launch the installation of the patch from the command line or by using an executable. To launch from the command line, use msiexec /p patch.msp REINSTALL=[Feature list] REINSTALLMODE=omus. To launch from an executable, call MsiApplyPatch or the ApplyPatch Method and provide the same command line arguments.
  2. When patching a client installation, the installer ignores the installation source and proceeds to patch the files that are already installed on the user's computer.
  3. The installer changes any patched components marked as run-from-source to run-locally. Users are unable to run these components from the source as long as the patch remains on the computer.
  4. The installer adds any transforms used to update the .msi file or adds patch-specific information to the user's profile.
  5. The installer caches the .msi file on the user's computer so that it can perform installation-on-demand, reinstall, and repair of the application. After a patch is applied to a stand alone installation, the installer references two or more source lists to external files: one for the original source and one for each patch that has been applied.


Small Updates by Reinstalling the Product

A small update can be applied to an application by completely or partially reinstalling the application.

To propagate the Small Update to current users (Complete Reinstall)

  1. This method launches a complete reinstallation of the application from the command line.
  2. From the command line use either: msiexec /fvomus [path to updated .msi file] or msiexec /I [path to updated msi file] REINSTALL=ALL REINSTALLMODE=vomus.
  3. The updated .msi file is cached on the user's computer. Note that it is not possible for the user to reinstall the product using Add/Remove Programs because the updated .msi file is not yet on the user's computer.

To propagate a Small Update to current users (Complete Reinstall)

  1. This method launches a complete reinstallation of the application from a program.
  2. From a program, call MsiReinstallProduct and specify REINSTALLMODE_PACKAGE, REINSTALLMODE_FILEOLDERVERSION, REINSTALLMODE_MACHINEDATA, REINSTALLMODE_USERDATA, and REINSTALLMODE_SHORTCUT
  3. The updated .msi file is cached on the users computer.

To propagate a Small Update to current users (Partial Reinstall)

  1. This method launches a reinstallation of only those features or components that are affected by the small update.
  2. Obtain a list of the names of features and components that are affected by the small update.
  3. From the command prompt use: msiexec /I [path to updated .msi file] REINSTALL=[Feature list] REINSTALLMODE=vomus .
  4. The updated .msi file is cached on the users computer.


Small Updates by Patching an Administrative Image

[This is preliminary documentation and subject to change.]

An administrative installation creates a source image of an application or product on a network. Users in a workgroup who have access to this administrative image can install the product from this source. Updating the application for this workgroup is done in two steps. First, the small update patch can be applied to the administrative image. Second, the changes in the small update need to be propagated to the users.

To apply a Small Update patch to an administrative image

  1. Obtain the small update in the form of a patch package. For example, the small update named Patch.msp.
  2. Obtain the path to the administrative image.
  3. From the command line use: msiexec /a [path to administrative image .msi file] /p patch.msp . This updates the application files and the .msi file of the administrative image. For a list of the options that can be used with Msiexec.exe, see Command Line Options. If during the original administrative installation SHORTFILENAMES was set to 1, and you are using an installer version earlier than Windows Installer version 1.5, you must also pass the SHORTFILENAMES property when applying the small update patch. Windows Installer version 1.5 or later versions automatically determine whether the administrative image is using short file names and sets the SHORTFILENAMES property.
  4. The resulting administrative image is the same as that produced by an administrative installation using a full product CD-ROM that includes the update. When new users install the application from this source they receive the updated application.

To propagate the Small Update to the workgroup

  1. Members of the workgroup obtain the changes by reinstalling the application from the administrative image using the procedure described in Small Updates by Reinstalling the Product.


Minor Upgrades

A minor upgrade and a Small Update differ in that a minor upgrade changes the package code and product version. As in the case of a small update, a minor upgrade does not change the product code. Minor upgrades provide product differentiation without actually defining a different product. See Small Updates for guidelines on the kinds of updates that can be handled by a small update or minor upgrade. Minor upgrades are shipped as a full product installation package or as a patch package.

Changing the product version indicates that there is an order to the different updates to the same product. For example, if a patch existed to update v9.0 to v9.1, and another patch existed to patch v9.1 to v9.2, the installer can enforce the correct order by checking the product version before applying the patch This also prevents the v9.1 to v9.2 patch from being applied to v9.0. For patches, this ordering is enforced through the product version validation bits set in the transforms included in the patch package.

Note that Windows Installer uses only the first three fields of the product version. For more information, see ProductVersion property. If you include a fourth field in your product version, the installer ignores the fourth field.

For information on how to apply a Minor Upgrade, see the following sections:

Small Updates by Patching the Local Installation of the Product
Small Updates by Reinstalling the Product
Small Updates by Patching an Administrative Image


Major Upgrades

A major upgrade is a comprehensive update of the product that warrants a change in the ProductCode property. A major upgrade can be shipped as a patch package or as a full product installation package. Major upgrades are available in Microsoft® Windows® Installer version 1.1 and later versions. Installer version 1.0 does not support updates that change the product code.

During a major upgrade using Windows Installer version 1.1 or later, the installer searches the user's computer for applications that are related to the pending upgrade, and upon detecting one, retrieves the version of the installed application from the system registry. The installer then uses information in the upgrade's database to determine whether upgrade the installed application.

To fully enable the installer's upgrade capabilities, every package should have an UpgradeCode property and an Upgrade table. Each record in the Upgrade table gives a combination of upgrade code, product version, and language information used to identify a set of products affected by the upgrade. When the FindRelatedProducts action detects that an affected product is installed on the system, it appends the product code to a property in the ActionProperty column of the Upgrade table. The RemoveExistingProducts action and the MigrateFeatureStates action remove or migrate the products listed in the ActionProperty list.

Note that Windows Installer uses only the first three fields of the product version. See ProductVersion property. If you include a fourth field in your product version, the installer ignores the fourth field.

Because Windows Installer version 1.1 supports upgrades that change the product code, package authors using earlier installer versions should follow the procedure described in Preparing an application for future major upgrades. This procedure ensures that an installation performed with Windows Installer version 1.0 is capable of using the upgrade capabilities of later installer versions.


How do I prevent an old package from installing over a newer version?

Windows Installer upgrade packages can be authored such that they will not install if the user has a newer version already installed. See also Preparing an Application for Future Major Upgrades.

To prevent an old package from installing over a newer version.

  1. Enter the UpgradeCode property for the group of related products that may be eligible to receive this upgrade into the UpgradeCode column of the Upgrade Table.
  2. Enter the msidbUpgradeAttributesOnlyDetect bit flag in the Attributes column of the Upgrade Table.
  3. Enter the version of the upgrade provided by this package into the VersionMin column of the Upgrade Table. Leave the VersionMax column blank.
  4. Enter the name of the property that is to be set by the FindRelatedProducts action into the ActionProperty column of the Upgrade table.
  5. Add the SecureCustomProperties Property and the property named in the ActionProperty column of the Upgrade Table to the Property Table.
  6. Add a Custom Action Type 19 after the FindRelatedProducts action in the InstallExecuteSequence Table. Include a record in the CustomAction table for this action and enter the text to be displayed in the Target column. The type 19 custom action is built into the installer and there's no code you need to write.
  7. Enter the name of the ActionProperty into the Condition column of the record in InstallExecuteSequence table containing the Custom Action Type 19. This conditions the custom action such that it will only be executed when the Upgrade table detects that a newer version is already installed.

    For example, a Windows Installer package that upgrades a group of related products to version 3.0 may include the following records in its Upgrade, CustomAction, InstallExecuteSequence, and Property tables. All the related products in the group have the same UpgradeCode, but the installer does not install this upgrade package if a version later than 3.0 is already installed on the computer. In this case, the installer presents an error message and the installation fails. The version 3.0 upgrade package will install over versions 1.0 and 2.0.

    Upgrade Table
    UpgradeCode | VersionMin | VersionMax | Language | Attributes | Remove | ActionProperty
    {E7BE6D45-49FF-4701-A17E-BDCC98CE180D} | 3.0 | msidbUpgradeAttributesOnlyDetect | NEWPRODUCTFOUND
    {E7BE6D45-49FF-4701-A17E-BDCC98CE180D} | 1.0 | 3.0 | msidbUpgradeAttributesVersionMinInclusive | UPGRADEFOUND

    CustomAction Table
    Action | Type | Source | Target
    CA1 | 19 | A higher upgrade is already installed.

    InstallExecuteSequence Table
    Action | Condition | Sequence
    FindRelatedProducts | 200
    CA1 | NEWPRODUCTFOUND | 201

    Property Table

Property | Value
SecureCustomProperties | NEWPRODUCTFOUND;UPGRADEFOUND


Preparing an Application for Future Major Upgrades

Although the Microsoft® Windows® Installer version 1.0 does not support major upgrades that change the product code, authors of installation packages should begin now to include upgrading information in their .msi files. This enables your application to take advantage of the full upgrading functionality available with future installer versions. Follow the procedure below to ensure that an installation done with version 1.0 of the installer is able to use the upgrade capabilities in future installer versions.

Every application, or suite of applications, should be assigned an UpgradeCode Property, ProductVersion Property, and ProductLanguage Property. The UpgradeCode property indicates a family of related applications consisting of different versions and different language versions of the same product.

Preparing an application for future major upgrades

  1. Determine a new ProductCode property for the application. See Changing the Product Code for more information. Enter ProductCode and its value into the Property table.
  2. Determine the application's version and the ProductVersion property. The ProductVersion should increase with each new version of the application. Note that Windows Installer uses only the first three fields of the product version. If you include a fourth field in your product version, the installer ignores the fourth field. Enter ProductVersion and its value into the Property table.
  3. Determine the language of the package and the ProductLanguage property. The value of this property must be a numeric language identifier (LANGID). Enter ProductLanguage and its value into the Property table. Note that the FindRelatedProducts action uses the language returned by MsiGetProductInfo. For FindRelatedProducts to work correctly, the package author must be sure that the ProductLanguage property is set in the Property table to a language that is also listed in the Template Summary Property.
  4. If you are authoring an installation package for the first version of your product, use a new UpgradeCode. If your package is intended for a newer version of an existing product, or is the same version as an existing product in a different language, use the same UpgradeCode as the existing product. No two products with the same ProductVersion and the same ProductLanguage can have the same UpgradeCode, unless one is a small update of the other.
  5. The UpgradeCode has the format of a GUID. Enter the UpgradeCode GUID into the Property table.

For more information, see How do I prevent an old package from installing over a newer version?.


Patching

Patch Packages

Creating a Patch Package

Downloading and Installing a Patch From the Internet

Patching Customized Applications

PATCHWIZ.DLL


Patch Packages

Microsoft® Windows® Installer uses a patch package to patch local or administrative installations. A patch package is a storage file, similar to a descriptor file, and has a .msp file name extension and its own CLSID. Patch packages are comprised of a summary information stream, transform sub-storages, and cabinet file streams.

A patch package does not include a database like a regular installation package. Instead it contains at minimum one database transform that adds patching information to the database of its target installation package. The installer uses this information to apply the patch files that are stored in the cabinet file stream of the patch package. For more information, see Creating a Patch Package.

Windows Installer version 1.0 allowed users who were not administrators to apply patches to applications being installed with elevated privileges. This has changed for Windows Installer version 1.1 so that only an administrator can apply a patch to an installation with elevated privileges. Non-administrator users can still apply a patch to applications not being installed with elevated privilege. If the AllowLockdownPatch policy has been set, non-administrator users can apply a patch to an existing product while running an installation at elevated privileges.

Patch packages are comprised of the following parts.

Summary Information Stream

The summary information stream holds a minimum of the following:

  • A GUID that uniquely identifies the patch. The GUID for this patch is appended with a list of GUIDs for earlier patches that are replaced by this patch.
  • A semicolon-delimited list of product codes for valid targets for this patch.
  • A semicolon-delimited list of transform sub-storage names in the order they are to be applied.
  • A semicolon-delimited list of sources for this patch.

Transform Sub-Storage

Transforms are used to update an application's database. Transforms can add or remove new files, registry entries, user interfaces, or customizations. Transforms are included in a patch package as sub-storages. Each sub-storage has its own summary information stream.

Two transforms are stored in the patch for each target database, and more than one pair of transforms can be in a patch if there are multiple targets. The first transform modifies the target to the new version. The second transform adds entries to the Patch, PatchPackage, Media, InstallExecuteSequence, and AdminExecuteSequence tables that provide file patching instructions to the installer.

The installer applies the transforms during a network administrative installation, and the changes then persist in the administrative image of the application's installer package. If the target is a local installation, however, the installer reapplies the transforms each time a maintenance mode or uninstall installation is invoked.

Cabinet File Stream

The cabinet file stream included in a patch can contain three types of files:

  • Patch files containing the information required to change the old version of the file into the new version. A single patch file can be used to update one or more old versions of a file.
  • Additional files being added to the application that are not present in the old version.
  • A entire replacement file. In the rare case where the new version of a file is smaller than the patch required to update the old version of that file, the new file can be included in its entirety. These are new files that are installed over their old versions.

See Also

Creating a Patch Package


Creating a Patch Package

Developers create a patch package by generating a patch creation file and using Msimsp.exe to call UiCreatePatchPackage in Patchwiz.dll. Msimsp.exe and Patchwiz.dll are provided in the Windows Installer SDK. The source code for Patchwiz.dll is also provided as an example so that you can customize and enhance the patch creation process. For more information see A Small Update Patching Example.

Because the application of a patch to a Windows Installer results in the installation of the original sources using a new .msi file, the new .msi file must remain compatible with the layout of the original source. This means that when authoring a patch package you must adhere to the following restrictions.

  • Do not change the primary keys in the File Table between the original and new .msi file versions.
  • Do not move files from one folder to another.
  • Do not move files from one cabinet to another.
  • Do not change the order of files in a cabinet.


Downloading and Installing a Patch From the Internet

Microsoft® Windows® Installer accepts a Uniform Resource Locator (URL) as a valid source for a patch. To install a patch located on a Web server at http://MyWeb/MyPatch.msp, use the following command line:

msiexec /p http://MyWeb/MyPatch.msp

Do not launch a patch by clicking on the link on the Web page showing the patch file's URL. Doing so can produce unexpected results.

You can also install a patch by using a script like the following:

<SCRIPT LANGUAGE="VBScript">
<!--
Dim Installer
On Error Resume Next
set Installer=CreateObject("WindowsInstaller.Installer")
Installer.ApplyPatch "http://server/share/patch.msi", "OriginalPackage.msi",0, "PROPERTY=VALUE "
set Installer=Nothing
-->
</SCRIPT>

See Also

Patch Packages, Creating a Patch Package, Patching Customized Applications, Downloading an Installation From the Internet


Patching Customized Applications

When installing a patch and one or more customization transforms to an application, usually the patch is installed first; followed by the customization transforms. By design, the patch is not broken by the subsequent installation of the customization transforms. However, installing the transforms first, followed by the patch, may break the customization.

For example, a break in the customization occurs when a patch is used to update a product from version 1 to version 2 and a customization transform that works for version 1 does not work for version 2. In this case, the version update patch cannot be applied to a customized product without first uninstalling and then reinstalling the original product.

Note that version validation used by the Microsoft Office Customization Wizard permits customizations to be used across changes in the product version. It is the responsibility of the developer to author their customization transform to be compatible across all versions if this is necessary for the product.


Changing the Product Code

The product code is a GUID that is the principal identification of an application or product. See Product Codes.

An update that meets the following guidelines generally does not require a change of the product code and can be handled as a Small Update, or if the version is to change, as a Minor Upgrade:

  • The update can enlarge or reduce the feature-component tree but it must not reorganize the existing hierarchy of features and components described by the Feature and FeatureComponents tables. It can add a new feature to the existing feature-component tree. If it removes a parent feature, it must also remove all the child features of the removed feature.
  • With Windows Installer versions earlier than version 1.5, the update can add a new component only if that component is associated with a new feature. Beginning with Windows Installer version 1.5, a new component can be added to an existing feature.
  • The update must not change the component code of any component. Consequently, a small update or Minor Upgrade must never change the name of a component's key file because this would require changing the component code.
  • The update must not change the name of the .msi file of the installation package. Instead, because it modifies the package, it should change the package code. Note that this means that the update can change the tables, custom actions, and dialogs in the .msi file without changing the file's name.
  • The update can add, remove, or modify the files, registry keys, or shortcuts of components that are not shared by one or more features. If the update modifies a versioned file, that file's version must be incremented in the File table. If the update removes resources, it should also update the RemoveFile and RemoveRegistry tables to remove any unused files, registry keys, or shortcuts that have already been installed.
  • The update of a component that is shared by two or more features must be backward compatible with all applications and features that use the component. The update can modify the resource of a shared component, such as files, registry entries, and shortcuts, as long as the changes are backward compatible. It is not recommended that the update add or remove files, registry entries, or shortcuts from a shared component.
  • A small update is shipped as a Windows Installer patch package. A full product CD-ROM is usually not provided with a small update.

The product code must be changed if an any of the following are true for the update:

  • Its a requirement that it be possible to have coexisting installations of the original and updated products on the same system.
  • The name of the .msi file has been changed.
  • The component code of an existing component has changed.
  • A component is removed from an existing feature.
  • An existing feature has been made into a child of an existing feature.
  • An existing child feature has been removed from its parent feature.
  • When using a version of Windows Installer earlier than version 1.5, the product code must be changed if a component has been added to an existing feature. With Windows Installer version 1.5, and later versions, a component may be added to an existing feature without requiring a product code change.

Note that adding a new child feature, consisting entirely of new components, to an existing feature does not require changing the product code.

A new child feature may be hidden from the user. To synchronize the installation state of a new child feature with its parent feature, set the msidbFeatureAttributesFollowParent and msidbFeatureAttributesUIDisallowAbsent bits for the child feature.


Transforms

Transforms alter the installation database and can be used to encapsulate the various customizations of a base package required by different groups of users. For example, in organizations where the finance and staff support departments require different installations of a product, the product's base package can be made available to everyone at one administrative installation point with the appropriate customizations distributed to each group of users separately as transforms. Administrators can also apply multiple transforms on-the-fly during an installation to efficiently assign the most appropriate installation to different users.

The following sections describe transforms:

About Transforms
Using Transforms


About Transforms

A transform is a collection of changes applied to an installation. By applying a transform to a base installation package, the installer can add or replace data in the installation database. The installer can only apply transforms during an installation.

The installer registers a list of transforms required by the product during the installation. The installer must apply these transforms to the product's installation package when configuring or installing the product. If a listed transform is unavailable, and if the transform source resiliency cannot restore it, the installation fails.

A transform can modify information that is in any persistent table in the Installer Database. A transform can also add or remove persistent tables in the Installer Database. Transforms cannot modify any part of an installation package that is not in a database table, such as information in the Summary Information Stream, information in substorages, information in nested installations, or files in embedded cabinets.

There are three types of Windows Installer transforms:

Embedded Transforms
Secured Transforms
Unsecured Transforms


Embedded Transforms

Embedded transforms are stored inside the .msi file of the package. This guarantees to users that the transform is always available when the installation package is available. Alternatively, transforms may be provided to users as stand-alone .mst files.

To add an embedded transform to the transforms list, add a colon (:) prefix to the filename. Because the installer can always obtain the transform from storage in the .msi file, embedded transforms are not cached on the user's computer. Embedded transforms may be used in combination with secured transforms or unsecured transforms. For more information, see Applying Transforms.


Secured Transforms

Secured transforms are sometimes necessary for security reasons. Secured transforms are stored locally on the user's computer in a location where, on a secure file system, the user does not have write access. Such transforms are cached in this location during the installation or advertisement of the package. During subsequent installation-on-demand or maintenance installations of the package, the installer uses the cached transforms.

To specify secured transform storage, set the TransformsSecure policy, set the TRANSFORMSSECURE property, or pass the @ or | symbol in the transforms list. Note that you cannot include secured and unsecured transforms in the same transforms list. See Applying Transforms.

The removal of the product by any user removes all secured transforms for that product from the user's computer.

If the installer finds that a secured transform is not locally available, it then attempts to restore the transform cache from a source. Secure transforms can be secure-at-source or secure-full-path:

  • Secure-At-Source Transforms that are missing from the local transform cache are restored from the root of the source of the .msi file.
  • Secure-Full-Path Transforms that are missing from the local transform cache are restored from the original full path specified by the transforms list.


Secure-At-Source Transforms

Secure-at-source transforms must have a source located at the root of the source for the package. When the package is installed or advertised, the installer saves the transforms on the user's computer in a cache where, on a secure file system, the user does not have write access. If the local copy of the transform becomes unavailable, the installer searches for a source to restore the cache. The method is the same as searching the source list for an .msi file. For more information, see Source Resiliency. The removal of a product by any user removes all secure transforms for that product from the user's computer.

To apply secure-at-source transforms at the installation of a package, set the TransformsSecure policy or the TRANSFORMSSECURE property, or make @ the first character passed in the transform list. Each transform must be indicated by a filename and must be located at the root of the source for the package. If any of the transforms are not located at the root of the package source, the installation fails. For more information, see Applying Transforms.


Secure-Full-Path Transforms

Secure-full-path transforms must have a source located at the full path specified in the TRANSFORMS property. When the package is installed or advertised, the installer saves the transforms on the user's computer in a cache where, on a secure file system, the user does not have write access. If the local copy of the transform becomes unavailable, it may only restore the cache using the specified path. The removal of a product by any user removes all secure transforms for that product from the user's computer.

To apply secure-full-paths transforms at the installation of a package, set the TransformsSecure policy or the TRANSFORMSSECURE property or make | the first character passed in the transform list. The full paths to the source of each transform must be passed in the transforms string. If any relative paths are in the list, the installation fails. The transform source does not have to be located with the source of the package.


Unsecured Transforms

[This is preliminary documentation and subject to change.]

Transforms that have not been secured as described in Secured Transforms are unsecured transforms by default.

To apply an unsecured transform when installing a package, pass the transform filenames in the TRANSFORMS property or command line string. Do not begin the string with the @ or | characters or set the TransformsSecure policy or the TRANSFORMSSECURE property. Note that you cannot combine unsecured transforms and secured transforms in the same TRANSFORMS list.

If the package is installed or advertised as a per-user installation, and has unsecured transforms, the installer saves the transform source in the Application Data folder in the user' profile. This enables a user to maintain their customization of a product while moving between computers.

If the package is installed or advertised as a per-machine installation, and uses unsecured transforms, the installer saves the transform source in the %windir%\Installer folder. This enables a user to maintain their customizations of a product while moving between computers.

During a first-time installation of the package, the installer first searches for the transform at the source supplied by the TRANSFORMS property or command line string. If this source is unavailable, the installer then searches for the transform at the source of the package next to the .msi file.

During a maintenance installation, the installer searches for the transform at the cache location. If the cached copy of the transform becomes unavailable, the installer searches for the transform at the source of the package next to the .msi file.

For more information, see Applying Transforms and Source Resiliency.


Using Transforms

Transforms increase the flexibility of application installation by providing a way of applying changes to a database without altering the original database. For more information, see Transforms.

The following sections discuss using transforms:

Applying Transforms
Generating a Transform
Using Transforms to Add Resources


Applying Transforms

The TRANSFORMS property contains the list of transforms for an installation package. The installer applies all the transforms in the transforms list at every installation, advertisement, installation-on-demand, or maintenance installation of the package.

The TRANSFORMS property is set by specifying the list of transforms on the command line; however, when using either the /jm or /ju command line option, the transforms list must be specified using the /t option.

Note that the transforms list cannot be modified once installed and can only be removed by uninstalling the application.

The following table provides examples of various transforms strings that could be added to the transforms list.

Transforms string | Description
transform1.mst;:transform2.mst;:transform3.mst | transform2.mst and transform3.mst are embedded transforms. transform1.mst is a secure-at-source transform only if the TRANSFORMSSECURE property or TransformsSecure policy is set, otherwise transform1 is an unsecured transform.
\\server\share\path\transform1.mst;:transform2.mst | transform2.mst is an embedded transform. transform1.mst is a secure-full-path transform only if the TRANSFORMSSECURE property or TransformsSecure policy is set, otherwise transform1 is an unsecured transform.
@:transform2.mst;transform1.mst @transform1.mst;:transform2.mst | transform2.mst is an embedded transform. transform1.mst is a stand-alone secure-at-source transforms.
|\\server\share\path\transform1.mst;:transform2.mst |:transform2.mst;\\server\share\path\transform1.mst | transform2.mst is an embedded transform. transform1.mst is a stand-alone secure-full-path transforms.


Generating a Transform

The following procedure describes a scenario to generate a transform that permanently hides a feature.

To permanently hide a product feature

  1. Copy the original installation package.
  2. Alter the copy by setting the value of the Display column in the Feature table to zero. This specifies hiding the feature.
  3. Create a transform from the original installation package to the new installation packages by calling MsiDatabaseGenerateTransform.
  4. Create the summary information in the transform by calling MsiCreateTransformSummaryInfo.

The transform is then ready to be applied during installation. For more information, see Applying Transforms.


Using Transforms to Add Resources

Resources that are needed for the customization of an application, such as corporate templates, can be deployed with the application by including a transform with the application's installation package. The following rules should be followed when deploying resources, such as files, registry keys, or shortcuts, using a transform.

  • The transform should add one or more new components to the installation database to contain the additional resources. The transform should not add resources to a component that already exists in the installation.
  • The transform should add one or more new features to the installation database to contain these new components. These new features should not be the parents of any existing features, but new parent and child features may be introduced together. New features should be given names that are unique across all other transforms for this product. No two transforms should ever add a feature to this product that has the same name listed in the Feature column of the Feature table and containing different components or resources.


Package Validation

It is strongly recommended that authors run validation on every new, or newly modified, installation package before attempting to install the package for the first time.

Package validation includes the following three parts:

  • Internal Validation
  • String-Pool Validation
  • Internal Consistency Evaluators - ICEs

Merge modules should be validated using the method described in Validating Merge Modules.


Internal Validation

When authoring an installation package, you can use the MsiViewModify function or the View.Modify method to ensure that the data you enter is syntactically correct. For more information, see Modify method. At the lowest level, a database table's column can store integers (short or long), strings, or binary data. However, an installation package requires specific integers or strings in certain tables. These specifications are maintained in the _Validation table. For example, the FileName column of the File table is a string column, but it specifically stores a filename. Therefore, not only should your entry be a string, but it should also follow the requirements for naming files.

The various validation enum values used with the MsiViewModify function allow for immediate validation at different levels. The MSIMODIFY_VALIDATE_FIELD enum can be used to validate individual fields of a record. It does not validate foreign keys. The MSIMODIFY_VALIDATE enum validates an entire row and includes foreign key validation. If you are inserting a new row into a table, use the MSIMODIFY_VALIDATE_NEW enum to verify that you are adding valid data as well as using unique primary keys. An insert fails if the primary keys are not unique. If a call to MsiViewModify with one of the validation enums returns an error, you can make repeated calls to MsiViewGetError for diagnosing the problem. MsiViewGetError indicates the column where the error occurred as well as the enum value to help fix the problem. For more information, see GetError method.

You can also use internal validation to ensure that other authors enter data correctly into your custom table. Add each of the columns of your custom table to the _Validation table using the custom table name and column name as the primary key. Provide a description or purpose of each column in the Description column of the _Validation table. Enter the applicable requirements for each column using the Nullable, MinValue, MaxValue, KeyTable, KeyColumn, Category, and Set columns:

  • If the column is Nullable, enter a 'Y'. If not, enter a 'N'.
  • If the column is an integer column and can contain a range of integers, enter that range using the MinValue and MaxValue columns.
  • Foreign key columns are identified using the KeyTable and KeyColumn columns.
  • For string columns, specify a Category such as Filename, GUID, Identifier, etc. For more information, see column data types.
  • If the data can only pertain to a specific number of values (string or integer), use the Set column to list the acceptable values.

The following is a list of the columns (in addition to Table, Column, and Description) in the _Validation table that can be filled in if your column is of the specified type. (Note that you do not have to fill in all the columns.)

Type | Columns
Integer | Nullable, MinValue, MaxValue, KeyTable, KeyColumn, Set
String | Nullable, KeyTable, KeyColumn, Category, Set, MinValue, MaxValue
Binary | Nullable, Category (Category must be "Binary")

Authoring environments may make use of MSIMODIFY_VALIDATE_DELETE. This enum assumes that you want to delete the row. No field or foreign key validation is performed. This enum actually performs a reverse foreign key validation. It checks the _Validation table for references in the KeyTable and KeyColumn columns for the table to which the "deleted" row belongs. If there are columns that list the table containing the "deleted" row as a potential foreign key, it cycles through that column to see if any of the values reference values in the "deleted" row. An error return means that you break the relational integrity of the database by deleting the row.


String-Pool Validation

The Microsoft® Windows® Installer stores all database strings in a single shared string pool to reduce the size of the database and to improve performance. The only means of validating the string pool is to use the MsiInfo tool found in the Windows Installer SDK.

String pool verification consists of two main checks: DBCS string tests and reference count verification.

DBCS string tests:

The DBCS string tests scan each string in the database for two criteria: For packages with a neutral code page marked, if any character is an extended character (greater than 127), the string is flagged and a message is displayed saying that the code page of the database is invalid because these characters require a specific code page to be rendered consistently on all systems.

If the database has a code page, each string is scanned for an invalid DBCS indicator. If a non-neutral string has been improperly marked, the characters will not render correctly. (This is most commonly caused by forcing the code page to a particular value using the _ForceCodepage table with non-neutral strings already in the database.) Note that this check requires that the code page of the database be installed on the system.

If there is a code page problem, the user may fix the error by using the _ForceCodepage table to force the code page of the database to the appropriate value. For details, see Code Page Handling.

Reference count verification:

To verify the reference counts of all strings, every table is scanned for string values, a count of each distinct string is kept, and the result is compared to the stored reference count in the database string pool.

If there is a string reference count problem, the user should immediately export each table of the database using MsiDatabaseExport, create a new database, and import the tables into the new database using MsiDatabaseImport. The new database then has the same content as the old database, but the string reference counts are correct. Adding or deleting data from a database with a corrupt string pool can increase corruption of the database and loss of data, so taking these steps quickly is important to prevent further data loss.

When rebuilding databases, remember to embed any necessary storages and streams in the new database (see _Streams Table and _Storages Table) and be aware of code page issues. Also remember to set each of the necessary Summary Information Stream properties.


Internal Consistency Evaluators - ICEs

Internal consistency evaluators, also called ICEs, are custom actions written in VBScript, JScript, or as a DLL or EXE. When these custom actions are executed, they scan the database for entries in database records that are valid when examined individually but that may cause incorrect behavior in the context of the whole database. Note that this is different than the validation done on individual records using MsiViewModify.

For example, the Component table may list several components that are all valid when tested individually with MsiViewModify. However, MsiViewModify would not catch the error when two components use the same GUID as their component code. The custom action ICE08 is designed to validate that the Component table does not contain duplicate component code GUIDs.

ICE custom actions return four kinds of messages:

  • Errors Error messages report database authoring that cause incorrect behavior. For example, duplicate component GUIDs cause the installer to incorrectly register components.
  • Warnings Warning messages report database authoring that causes incorrect behavior in certain cases. Warnings can also report unexpected side-effects of database authoring. For example, entering the same property name in two conditions that differ only by the case of letters in the name. Because the installer is case-sensitive, the installer treats these as different properties.
  • Failures Failure messages report the failure of the ICE custom action. Failure is commonly caused by a database with such severe problems that the ICE cannot even run.
  • Informational Informational messages provide information from the ICE and do not indicate a problem with the database. Often they are information about the ICE itself, such as a brief description. They can also provide progress information as the ICE runs.

For more information, see Using Internal Consistency Evaluators.


Using Internal Consistency Evaluators

To validate a database, use a special validation tool to merge a .cub file containing the Internal Consistency Evaluators (ICEs) into your database, execute the ICEs, and report the results. Several such tools are provided in the Platform SDK. Authoring environments from third-party vendors also may incorporate the ICE validation system into their authoring environment. It is also possible to write your own tool to perform ICE validation. Most ICE validation tools merge the .cub file and your database into a third, temporary database. Microsoft® Windows® Installer displays warnings, errors, debugging information, and API errors as it executes each ICE in the .cub file. When the installer finishes executing the ICEs it closes the .msi file, .cub file, and temporary database without saving any changes. The .msi file and .cub file remain unchanged by the validation test.

ICE custom actions communicate to the user by calling MsiProcessMessage and posting an INSTALLMESSAGE_USER message. An ICE message commonly returns information such as the following:

  • Name of the ICE that has found an error
  • Date the ICE was created
  • Author of the ICE
  • Date the ICE was last modified.
  • Description of the API error causing the ICE to fail
  • Description of an error
  • A warning to the user
  • Name of the database table containing the error or warning
  • Name of the table column containing the error or warning
  • Primary keys of the table containing the error or warning
  • A URL to a HTML file giving debugging suggestions
  • A string that can contain other information

Authors of installation packages can write ICE custom actions or use the standard set of ICEs included in the .cub files provided with the SDK. For more information on how to write an ICE, see Building an ICE.

After writing the appropriate ICEs for validation, a developer must collect the custom actions together into an .msi database, called a .cub file, that contains only the ICEs and their required tables. A .cub file cannot be installed and is used only to store and provide access to ICE custom actions. For more information on making .cub files, see Building an ICE Database. Alternatively, developers can validate their installation package using the existing ICEs described in ICE Reference. These ICEs can be obtained from standard .cub files provided with the SDK.

Starting with Windows Installer version 1.1 SDK, the installation of the database table editor Orca or the validation tool msival2 provides the Logo.cub, Darice.cub, and Mergemod.cub files. The set of ICEs in the Logo.cub file is a subset of those in the Darice.cub file. If your package passes validation using Darice.cub, it will pass with Logo.cub. Mergemod.cub contains a set of ICEs used to validate merge modules. For more information, see Merge Module ICE Reference.

To validate an installation package

  1. Obtain or author the appropriate ICE custom actions. You may be able to use one or more of the existing ICEs described in the ICE Reference. If your validation requires an ICE not yet in this list, you can create a new ICE as described in Building an ICE.
  2. Prepare an ICE Database containing all the ICE custom actions. See the section Building An ICE Database for information about preparing a .cub file.
  3. Merge the .cub file containing your ICE database into the .msi file, then execute the ICE custom actions using a validation tool.

Note that merge modules should be validated as described in Validating Merge Modules.


Building An ICE

If you are unable to find the Internal Consistency Evaluators you need among the existing ICE custom actions listed in the ICE Reference, you will need to prepare your own ICE to validate your package.

When authoring ICE custom actions you should do the following:

  • Base the ICEs only on custom actions of types listed in the table shown.
  • Call MsiProcessMessage and post an INSTALLMESSAGE_USER type of message. When authoring your ICE messages follow the message format in the ICE Message Guidelines.
  • Write your ICE such that it captures any API errors and always returns ERROR_SUCCESS. This is necessary to allow subsequent custom actions to run following the failure of an ICE.

ICE custom actions are limited to the following custom action types.

Custom action type | Description
Custom Action Type 1 | DLL in binary stream
Custom Action Type 2 | EXE in binary stream
Custom Action Type 5 | JScript in binary stream
Custom Action Type 6 | VBScript in binary stream
Custom Action Type 37 | JScript code as string
Custom Action Type 38 | VBScript code as string

When authoring an ICE custom action, do not do the following:

  • Do not assume that the handle to the engine that the ICE receives is an installation instance of the installer database. If it is not a installation instance, certain properties are not defined, the source and target directories are not resolved, and current feature states are not defined.
  • Do not rely on the prior execution, or non-execution, of any installer action, custom action, or another ICE. Because a prior ICE may have created temporary columns in any table, authors should reference columns by name whenever possible. ICEs should cleanup any temporary columns or tables before they exit.
  • Do not assume that authors have access to an image of the source directory of the database.
  • Do not assume that changes made to the database do not persist.

See also

Sample ICE in C++., Sample ICE in VBScript


ICE Message Guidelines

ICE custom actions communicate by calling MsiProcessMessage and posting an INSTALLMESSAGE_USER type message.

When authoring a message string for an ICE custom action, format the string as follows.

Name of ICE <tab> Message Type <tab> Description <tab> Help URL or location <tab> Table Name <tab> Column Name <tab> Primary Key <tab> Primary Key <tab> Primary Key . . . (repeat for as many primary keys as needed)

The first three fields of the string are required in every message.

The Message Type field specifies whether the ICE reports a Failure, Error, Warning, or Informational message.

Value | Message type
0 | Failure message reporting the failure of the ICE custom action.
1 | Error message reporting database authoring that cause incorrect behavior.
2 | Warning message reporting database authoring that causes incorrect behavior in certain cases. Warnings can also report unexpected side-effects of database authoring.
3 | Informational message.

If help is not available, the Help URL field may be the empty string.

Error and Warning messages should provide the Table Name, Column Name, and Primary Key fields. If any of these fields are omitted, all of the fields following the first blank field must be left out of the message. For example, a table name is provided without a column name and primary keys or a table name and a column name is provided with no primary keys. However a column name and primary keys cannot be used without a table name. Multiple primary keys may be listed until all the primary keys in that table have been given values.

Examples

The first message illustrated by the Sample ICE in C++:

"ICE01\t3\tCreated 04/29/1998 by <insert author's name here>."

The second message posted by the sample ICE:

"ICE01\t3\tLast modified 05/06/1999 by <insert author's name here>."

The third message posted by the sample ICE.

"ICE01\t3\tSimple ICE to illustrating the ICE concept".


Sample ICE in C++

This sample code is from an ICE custom action (ICE01). It validates that the ICE mechanism is working by displaying the time. The ICE posts a message giving the time the installer called the ICE. This ICE should never return an error.

// test of external database access
#include <windows.h>
#include <stdio.h>
#include <tchar.h>
#include "MsiQuery.h"

///////////////////////////////////////////////////////////
// ICE01 - simple ICE that doesn't test anything
UINT __stdcall ICE01(MSIHANDLE hInstall)
{
// setup the record to describe owner and date created
PMSIHANDLE hRecCreated = ::MsiCreateRecord(1);
::MsiRecordSetString(hRecCreated, 0, TEXT("ICE01\t3\tCreated 04/29/1998 by <insert author's name here>"));

// post the owner message
::MsiProcessMessage(hInstall, INSTALLMESSAGE(INSTALLMESSAGE_USER), hRecCreated);
// setup the record to describe the last time the ICE was modified
::MsiRecordSetString(hRecCreated, 0, TEXT("ICE01\t3\tLast modified 05/06/1998 by <insert author's name here>"));

// post the last modification message
::MsiProcessMessage(hInstall, INSTALLMESSAGE(INSTALLMESSAGE_USER), hRecCreated);

// setup the record to describe what the ICE evaluates
::MsiRecordSetString(hRecCreated, 0, TEXT("ICE01\t3\tSimple ICE illustrating the ICE concept"));

// post the description of evaluation message
::MsiProcessMessage(hInstall, INSTALLMESSAGE(INSTALLMESSAGE_USER), hRecCreated);
// time value to be sent on
TCHAR szValue[200];
DWORD cchValue = sizeof(szValue)/sizeof(TCHAR);

// try to get the time of this call
if (MsiGetProperty(hInstall, TEXT("Time"), szValue, &cchValue) != ERROR_SUCCESS)
lstrcpy(szValue, TEXT("(none)")); // no time available

// setup the record to be sent as a message
PMSIHANDLE hRecTime = ::MsiCreateRecord(2);
::MsiRecordSetString(hRecTime, 0, TEXT("ICE01\t3\tCalled at [1]."));
::MsiRecordSetString(hRecTime, 1, szValue);

// send the time
::MsiProcessMessage(hInstall, INSTALLMESSAGE(INSTALLMESSAGE_USER), hRecTime);

return ERROR_SUCCESS; // allows other ICEs will continue
}


Sample ICE in VBScript

This sample code is from an ICE custom action (ICE08). The ICE validates that every component in the Component table has a unique GUID. No validation is done if the Component table does not exist.

Function ICE08()

'Give creation data
Set recInfo=Installer.CreateRecord(1)
recInfo.StringData(0)="ICE08" & Chr(9) & "3"
    & Chr(9) & "Created 05/21/98 by <insert
    author's name here>"
Message &h03000000, recInfo

'Give last modification date
recInfo.StringData(0)="ICE08" & Chr(9) & "3"
    & Chr(9) & "Modified 05/21/98 by <insert
    author's name here>"
Message &h03000000, recInfo

'Give description of test
recInfo.StringData(0)="ICE08" & Chr(9) & "3"
    & Chr(9) & "Checks for duplicate GUIDs
    in Component table"
Message &h03000000, recInfo

'Is there a Component table in the database?
iStat = Database.TablePersistent("Component")
If 1 <> iStat Then
recInfo.StringData(0)="ICE08" & Chr(9) & "2"
    & Chr(9) & "Table: 'Component' missing.
    ICE08 cannot continue its validation."
    & Chr(9) & "http://mypage2"
Message &h03000000, recInfo
ICE08 = 1
Exit Function
End If

'process component table
Set view=Database.OpenView("SELECT
    `Component`,`ComponentId` FROM
    `Component` ORDER BY `ComponentId`")
view.Execute
Do
Set rec=view.Fetch
If rec Is Nothing Then Exit Do

'compare for duplicate
If lastGuid=rec.StringData(2) Then
rec.StringData(0)="ICE08" & Chr(9)
    & "1" & Chr(9) & "Component: [1]
    has a duplicate GUID: [2]" & Chr(9)
    & "http://mypage2" & Chr(9) &
    "Component" & Chr(9) & "ComponentId" & Chr(9) & "[1]"
Message &h03000000,rec
End If

'set for next compare
lastGuid=rec.StringData(2)
Loop

'Return iesSuccess
ICE08 = 1

End Function


Building an ICE Database

After selecting the appropriate ICEs for validation, a developer must collect the custom actions together into an ICE database. A .cub file is a standard .msi database that contains only ICEs and their required tables. A .cub file cannot be installed and is used only to store and provide access to ICE custom actions.

A .cub file contains the following database tables.

Table | Description
Binary | The script files, DLLs, and EXEs of the ICE customs actions that are referenced in the CustomAction table.
CustomAction | Each record in this table corresponds to an ICE custom action included in the .cub file.
_ICESequence | This table lists the ICE customs actions included in the .cub file in their execution sequence. The ICE custom actions listed in this table are executed by calling MsiSequence , or individually excuted using MsiDoAction.
_Validation | This table contains the .cub file entries that are to be merged into the _Validation table.
_Special | Any special processing tables required by particular ICE custom actions must be included in the .cub file. The name of these tables must have a leading underscore.

See Sample .cub File.


Sample .cub File

This sample illustrates the layout of a .cub file containing two ICEs. The installer executes the custom actions in the sequence: ICE01 and ICE08.

The custom action ICE01 is a Custom Action Type 1. It is an entry point to a DLL that is stored as a stream in the .cub file. This stream is listed in the Binary Table ice.dll.

The custom action ICE08 is a Custom Action Type 6. It is an entry point to a function in VBScript that is stored as a stream in the .cub file. This stream is listed in the Binary Table as ice.vbs.

Binary Table

Name | Data
ice.vbs | Unformatted binary data of ice.vbs
ice.dll | Unformatted binary data of ice.dll

CustomAction Table

Action | Type | Source | Target
ICE01 | 1 | ice.dll | ICE01
ICE08 | 6 | ice.vbs | ICE02

_ICESequence Table

Action | Condition | Sequence
ICE01 |  | 10
ICE08 |  | 20

_Special Table

ICE01 and ICE08 do not require the inclusion of special processing tables. When the .cub file contains special tables they must also be included in the _Validation Table.

_Validation Table

Table | Column | Nullable | MinValue | MaxValue | KeyTable | KeyColumn | Category | Set | Description
Binary | Name | N |  |  |  |  | Identifier |  |
Binary | Data | N |  |  |  |  | Binary |  |
CustomAction | Action | N |  |  |  |  | Identifier |  |
CustomAction | Type | N |  |  |  |  | Integer |  |
CustomAction | Source | Y |  |  |  |  | CustomSource |  |
CustomAction | Target | Y |  |  |  |  | Formatted |  |
_ICESequence | Action | N |  |  |  |  | Identifier |  |
_ICESequence | Condition | Y |  |  |  |  | Condition |  |
_ICESequence | Sequence | Y |  |  |  |  | Integer |  |


ICE Reference

The following list provides links to each individual ICE. These ICEs are used to validate installation packages. See Merge Module ICE Reference for a list of the ICEMs used to validate merge modules.

ICE | Brief description of ICE
ICE01 | Simple test of ICE mechanism.
ICE02 | Circular reference test for File-Component, Registry-Component KeyPaths.
ICE03 | Basic data and foreign key validation.
ICE04 | Validates file sequence numbers against the Media table's LastSequence numbers.
ICE05 | Validates for "required" entries in particular tables.
ICE06 | Validates for missing column or tables in the database. Any column defined in the _Validation table must be found in the database.
ICE07 | Validates that fonts are installed to the FontsFolder
ICE08 | Checks for duplicate GUIDs in the ComponentId column of the Component table.
ICE09 | Validates that the permanent bit is set for every component marked for installation into the SystemFolder.
ICE10 | Ensures that advertise feature states among children and parents are compatible.
ICE11 | ICE11 validates the Source column of the Custom Action table for Nested Installation custom actions. The Source column must contain a valid GUID (MSI product code).
ICE12 | Validates type 35 and type 51 custom actions and their locations in the sequence tables.
ICE13 | Validates that dialogs are not listed as actions in the execute sequence tables. Dialog actions are only allowed in the user interface sequence tables.
ICE14 | Validates that feature parents do not have msidbFeatureAttributesFollowParent bit set. Also validates that the entries in the Feature and Feature_Parent columns are not the same in the same record.
ICE15 | Validates that a circular reference exists between every entry in the MIME table and the corresponding extension in the Extension table.
ICE16 | Validates that the ProductName in the Property table is not greater than 63 characters in length.
ICE17 | Validates control type dependencies in the Control table. Covers PushButtons, RadioButtonGroups, ListBoxes, ListViews, and ComboBoxes
ICE18 | Validates the KeyPath column of the Component table when it is NULL. In this case, the key path is a Directory.
ICE19 | Validates the advertising tables: Class, TypeLib, Extension, PublishComponents, and Shortcut.
ICE20 | Validates that the required dialogs are in the Dialog table.
ICE21 | Validates that all components in the Component table map to a feature in the FeatureComponents table.
ICE22 | Validates that the Feature_ and Component_ columns in the PublishComponent table.
ICE23 | Validates the tab order of controls in all dialog boxes.
ICE24 | Validates certain properties in the Property table.
ICE25 | Verifies merge module dependencies and merge module exclusions.
ICE26 | Validates required and prohibited actions in the sequence tables.
ICE27 | Validates the organization and order of the sequence tables.
ICE28 | Validates actions that must not be separated by ForceReboot.
ICE29 | Validates that your stream names remain unique if truncated to the 62 chararacter limit.
ICE30 | Validates that the installation of components containing the same file never installs the file more than once in the same directory.
ICE31 | Validates the text styles listed in the Text column of the control table.
ICE32 | Compares the column definitions to validates that keys and foreign keys are of the same size and type.
ICE33 | Checks for entries in the registry table that belong in other tables.
ICE34 | Validates that every group of radio buttons has a default.
ICE35 | Validates that any files from a cabinet file cannot be set to run from source
ICE36 | Validates that icons listed in the Icon table are used the Class, ProgID, or Shortcut tables.
ICE38 | Validates that components installed under the user's profile use a registry key under HKCU as their key path.
ICE39 | Validates the Summary Information stream of the database.
ICE40 | Performs various miscellaneous checks
ICE41 | Validates that entries in the Extension and Class tables refer to components belonging to the referenced feature.
ICE42 | Checks that Class table entries don't have EXEs set as InProc, and that only LocalServer contexts have arguments and DefInProc values.
ICE43 | Checks that non-advertised shortcuts are in components with HKCU reg keys as the key paths.
ICE44 | Checks that dialog events in the ControlEvent table (NewDialog, SpawnDialog, SpawnWaitDialog) reference valid Dialogs in the Dialog table.
ICE45 | Checks for reserved bits that are set.
ICE46 | Checks for custom properties that only differ from defined properties by their case.
ICE47 | Checks for features with more than 1600 components per feature on Windows NT/Windows 2000 and more than 800 components per feature on Windows 95 and Windows 98.
ICE48 | Checks for directories that are hard-coded to local paths.
ICE49 | Checks for non-REG_SZ default values in the registry table.
ICE50 | Checks that advertised shortcuts have correct icons and context menus.
ICE51 | Checks that TTC/TTF fonts do not have titles, but that all other fonts do.
ICE52 | Checks for non-public properties in the AppSearch table.
ICE53 | Checks for registry entries that write private installer information or policy values.
ICE54 | Checks for components using companion files as their key path file.
ICE55 | Checks that LockPermission objects exist and have valid permissions.
ICE56 | Validates that the directory structure of the .msi file has a single valid root.
ICE57 | Validates that individual components do not mix per-machine and per-user data.
ICE58 | Checks that your Media table does not have more than 80 rows.
ICE59 | Checks that advertised shortcuts belong to components that are installed by the target feature of the shortcut.
ICE60 | Checks that if a file in the File table is not a font and has a version, then it also has a language.
ICE61 | Checks the Upgrade table.
ICE62 | Performs extensive checks on the IsolatedComponent table for data that may cause unexpected behavior.
ICE63 | Checks for proper sequencing of the RemoveExistingProducts action.
ICE64 | Checks that new directories in the user profile are removed in roaming scenarios
ICE65 | Checks that the Environment table does not have invalid prefix or append values.
ICE66 | Uses the tables in the database to determine which schema your database should use.
ICE67 | Checks that the target of a non-advertised shortcut belongs to the same component as the shortcut itself, or that the attributes of the target component ensure that it does not change installation locations.
ICE68 | Checks that all custom action types needed for an installation are valid.
ICE69 | Checks that all substrings of the form [$componentkey] within a Formatted string do not cross-reference components.
ICE70 | Verifies that integer values for registry entries are specified correctly
ICE71 | ICE71 verifies that the Media table contains an entry with DiskId equal to 1.
ICE72 | ICE72 ensures that the only custom actions used in the AdvtExecuteSequence table are type 19, type 35, and type 51 custom actions
ICE73 | ICE73 verifies that your package does not reuse package codes or product codes of the Windows Installer SDK samples. See Package Codes and Product Codes.
ICE74 | ICE74 verifies that the FASTOEM property has not been authored into the Property Table.
ICE75 | ICE75 verifies that all custom action types that use an installed file as their source are sequenced after the CostFinalize action.
ICE76 | ICE76 verifies that no files in the BindImage table reference SFP (WFP) catalogs.
ICE77 | ICE77 verifies that in-script custom actions are sequenced after the InstallInitialize action and before the InstallFinalize action.
ICE78 | ICE78 verifies that that the AdvtUISequence table either does not exist or is empty.


ICE01

ICE01 validates that the ICE mechanism is working. This ICE uses the Time property to get the time and returns either the system time or None.

Result

ICE01 posts a message giving the time the installer called ICE01. This ICE should never return an error.

See Also

ICE Reference


ICE02

ICE02 validates that certain references between the Component, File, and Registry tables are reciprocal. These references must to be reciprocal for the installer to correctly determine the installation state of components.

The installer uses the KeyPath column of the Component table to detect the presence of the component listed in the Component column. The KeyPath column contains a key into the Registry or File tables. Both of these tables have a Component_ column that contains a key back into the Component table pointing to the component that controls the registry entry or file. These references must be reciprocal.

Result

ICE02 posts an error message if it finds a reference that should be reciprocal and is not.

Example

ICE02 would post the following error message for a .msi file containing the database entries shown.

File: 'Red_File' cannot be the key file for Component: 'Blue'. The file belongs to Component: 'Red'

Component Table (partial)

Component | KeyPath
Red | Red_File
Blue | Red_File

File Table (partial)

File Column | Component_
Red_File | Red
Blue_File | Blue

Component Blue references Red_File, but Red_File is not controlled by Component Blue and therefore cannot be the KeyPath file. If the installer were called to get the installation state of Blue it would incorrectly check whether Red_File was installed. Changing the KeyPath field for Blue in the Component Table to Blue_File fixes the error.

See Also

ICE Reference


ICE03

ICE03 validates the data types and foreign keys based on the _Validation table and the database tables in the .msi file.

Result

ICE03 posts the following messages for the validation errors.

ICE03 error message | Description
Duplicate Primary Key | The primary keys of a new row duplicates the primary keys of an existing row. The Nullable column of the _Validation table shows the primary keys in the database.
Not A Nullable Column | A table column that is not specified as nullable in the Nullable column of the _Validation table contains an entry that is Null.
Not A Valid Foreign Key | A column that is a foreign key into a second table contains an entry that does not exist in the primary key of the second table.
Value exceeds MaxValue | The numeric value of an entry in a database table exceeds the maximum limit specified for this field in the MaxValue column of the _Validation table.
Value below MinValue | The numeric value of an entry in a database table is less than the minimum limit specified for this field in the MinValue column of the _Validation table.
Value not a member of the set | The value of an entry in a database table is not a member of the acceptable set of values specified for this field in the Set column of the _Validation table.
Invalid version string | See the Version data type.
All UPPER case required | See the UpperCase data type.
Invalid GUID string | See the GUID data type.
Invalid filename/usage of wildcards | The database contains an invalid filename or an incorrect wildcard. See the WildCardFilename data type.
Invalid identifier | See the Identifier data type.
Invalid Language Id | The database contains an invalid numeric Language Identifier (LANGID). See the Language data type. See the platform SDK for a current list of Language Identifiers used by Windows. For example, 1033 for the U.S. and 0 for language neutral.
Invalid Filename | See the Filename data type.
Invalid full path | See the Path, AnyPath, and Paths data types.
Bad conditional string | The database contains an invalid conditional string. This is a text string that must evaluate to TRUE or FALSE according to the Conditional Statement Syntax. See the Condition data type.
Invalid format string | See the Formatted data type.
Invalid template string | See the Template data type.
Invalid DefaultDir string | See the DefaultDir data type.
Invalid registry path | See the RegPath data type.
Bad CustomSource data | See the CustomSource data type.
Invalid property string | See the Property data type.
Missing data in _Validation table or old Database | There are columns in the database that are not listed in the Column column of the _Validation table. The database and _Validation table do not match
Bad cabinet syntax/name | See the Cabinet data type.
_Validation table: Invalid category string | This is an error in authoring the _Validation table. Validation does not recognize the category string used for this particular column in the _Validation table. See Column Data Types and specify a valid category.
_Validation table: Data in KeyTable column is incorrect | The KeyTable column in the _Validation table references a table that does not exist in the database.
_Validation table: Value in MaxValue column < that in MinValue column | This is an error in authoring the _Validation table. Min must always be less than or equal to Max.
Bad shortcut target | See the Shortcut data type.
String overflow (greater than length permitted in column) | The string's length is greater than the column width specified by the column definition. Note that the installer does not internally limit the column width to the specified value. See Column Definition Format.
Undefined error | Unknown error.
Column cannot be localized | Primary key columns cannot be localized.

See Also

ICE Reference


ICE04

ICE04 validates that the sequence number of every file in the File table is less than or equal to the largest sequence number in the LastSequence column of the of the Media table.

Each record in the Media table represents a disk on the source media containing all the files with a sequence number less than or equal to the value in the LastSequence column and greater than the LastSequence value in the record of the preceding disk.

Result

ICE04 posts an error message if there is a file with a sequence number greater than the largest LastSequence number for the source media.

Example

ICE04 would report the following error for the example shown:

File: MyFile, Sequence: 210 Greater Than Max Allowed by Media Table.

File Table (partial)

File | Sequence
MyFile | 210

Media Table (partial)

DiskId | LastSequence
1 | 100

See Also

ICE Reference


ICE05

ICE05 validates that certain tables contain required entries. This includes, but is not restricted to, checking the Property table for the required properties: ProductName, ProductLanguage, ProductVersion, ProductCode, and Manufacturer.

Result

ICE05 posts an error if a required entry is missing.

Example

For the example shown, ICE05 would report that the entry: 'ProductVersion' is required in the 'Property' table.

Property Table (partial)

Property | Value
ProductName | MyProduct

See Also

ICE Reference


ICE06

ICE06 checks every table to validate that all the columns listed in the _Validation table are present in the table. If a table does not exist, any _Validation entries for that table are ignored.

The purpose of ICE06 is to detect instances in which an author tries to use a new _Validation table that reflects a schema change with an old database that has not been updated. ICE06 also detects the reverse case of an old _Validation table being used with an altered database.

Note that the internal validation performed by ICE03 catches the instance of a table column not defined in the _Validation table being listed in the columns catalog. The use of both ICE03 and ICE06 therefore ensures every column in the database is tested.

Result

ICE06 posts an error when there is a table column defined in the _Validation table that is not listed in the _Columns table.

Example

For the following example ICE06 posts the message

Column: Version of Table: ModuleSignature is not defined in database.

_Validation Table (partial)

Table | Column
ModuleSignature | ModuleID
ModuleSignature | Version

_Columns Table (partial)

Table | Number | Name
ModuleSignature | 1 | ModuleID

The Version column of the ModuleSignature table is not in the database or listed in the _Columns table.

See Also

ICE Reference


ICE07

ICE07 validates that installation package specifies that fonts be installed into the FontsFolder. If a font is installed to a folder other than the FontsFolder the installer creates a shortcut rather than actually installing the font.

The ICE07 custom action does the following for each font in the Font table.

  1. Finds the font file to which each font title belongs using the Font table.
  2. Queries the Component_ column of the File table for the component that controls each file.
  3. Queries the Directory_ column of the Component table to obtain a key into the Directory table.
  4. Resolves the Directory table to determine the name of the folder into which the installer is to install the font file
  5. Posts an error if the font file is being installed into a folder other than the FontsFolder.

Result

ICE07 posts an error if it finds that the database specifies that a font file be installed into a folder other than the FontsFolder.

Example

IC07 would post the following error message for the example shown.

'Tahoma' is a font and must be installed to the FontsFolder directory. Current Install Directory: 'Sandbar'.

Font Table

File_ | FontTitle
Myrtle | Tahoma

File Table (partial)

File | Component_
Myrtle | Myrtle_Beach

Component Table (partial)

Component | Directory_
Myrtle_Beach | SandBar

In this example, the font Tahoma maps to the font file Myrtle. The file Myrtle belongs to the component Myrtle_Beach. Resolution of the Directory table shows that all the files belonging to Myrtle_Beach are to be installed in the Sandbar folder. Because this is not the FontsFolder, ICE07 posts an error message.

Note that if the component Myrtle_Beach really belongs in the Sandbar folder, and not the FontsFolder, then the font Tahoma may not belong in Myrtle_Beach. A possible fix for the error would be to include Tahoma in another component that does get installed in the FontsFolder directory.

See Also

ICE Reference


ICE08

ICE08 validates that the Component table contains no duplicate GUIDs. Every component must have a unique GUID. No validation is done if the Component table does not exist.

Result

ICE08 posts an error message if two or more entries in the ComponentId column of the Component table contain the same GUID.

Example

For the following example, ICE08 would post a message stating that components Red and Green have duplicate GUIDs.

Component Table (partial)

Component | ComponentId
Red | {0000000A-0003-0000-0000-624474736554}
Blue | {0000000A-0003-0000-0000-624474736354}
Green | {0000000A-0003-0000-0000-624474736554}

To fix this error, change either of the duplicate GUIDs.

See Also

ICE Reference


ICE09

ICE09 validates that the permanent bit is set for every component marked for installation into the SystemFolder. ICE09 posts a warning because you should avoid installing non-permanent system components to the SystemFolder. To prevent this warning, set the Permanent bit in the Attributes column of the Component table for every component that is marked for installation into the SystemFolder. No validation is done if the database does not have a Component table.

See Also

ICE Reference


ICE10

ICE10 validates that the advertise state of child features matches that of its parent feature. If a parent feature favors or disallows advertisement, its child features must similarly favor or disallow advertisement.

The ICE10 custom action determines the state of parent and child features from the Attributes column of the Feature table. Note that it is valid to set the state of a feature to 0 and have its parent or child set to favor or disallow advertisement.

Result

ICE10 posts an error if the Attributes column of the Feature table contains a mismatch in the advertise state.

Example

ICE10 posts the following error message for the example shown.

Conflicting states, one favors, one disallows. Child: Word differs in advertise state
from Parent: Office.

Note for this example that Microsoft Excel and Microsoft Word are child features of Microsoft Office.

Feature Table (partial)

Feature | Feature_Parent | Attributes
Office | NULL | 8
Excel | Office | 8
Word | Office | 4

Word is set to favor advertise, conflicts with the disallow advertise state of the parent Office.

In some cases ICE10 posts the following error:

Parent feature: 'Parent' not found for child feature: 'Child'. This error means
that for the child feature 'Child', the feature 'Parent' is not listed in the
Feature table.

This refers to an invalid foreign key reference. The fix is to have 'Child' point to its correct parent feature, or add an entry for the parent feature 'Parent' to the feature table.

See Also

ICE Reference


ICE11

ICE11 validates the Source column of the CustomAction table for Nested Installation custom Actions. The Source column must contain a valid GUID (MSI product code).

Result

ICE11 posts an error if the Source column of the CustomAction table is authored incorrectly for nested installlation custom actions.

Example

ICE posts the following error messages for the example shown.

CustomAction: CA4 is a nested install of an advertised MSI.  The 'Source' must contain a valid MSI product code.  Current: ProductCode.
CustomAction: CA1 is a nested install of an advertised MSI.  It duplicates the ProductCode of the base MSI package.  Current: {BFB69273-F0AE-45C4-9853-0AF946714768}.
CustomAction: CA2 is a nested install of an advertised MSI.  The GUID must be all upper-case.  Current: {BFB69273-F0AE-55c5-9853-0AF946714768}.

Property Table (partial)

Property | Value
ProductCode | {BFB69273-F0AE-45C4-9853-0AF946714768}

CustomAction Table (partial)

CustomAction | Type | Source
CA1 | 39 | {BFB69273-F0AE-45C4-9853-0AF946714768}
CA2 | 39 | {BFB69273-F0AE-55c5-9853-0AF946714768}
CA3 | 39 | {BFB69273-F0AE-66C6-9853-0AF946714768}
CA4 | 39 | ProductCode

Fixing the errors is easy. For CA1, you cannot do a nested-installation of the "base package". This would result in a recursive installation. This entry should be removed or the Source column should be changed to a GUID for an advertised MSI that differs from the base package's GUID. For CA2, make all characters of the GUID uppercase. Lastly, change CA4's Source column to reference a valid GUID of an advertised MSI.

See Also

ICE Reference


ICE12

ICE12 queries the CustomAction, Directory, AdminExecuteSequence, AdminUISequence, AdvtExecuteSequence, InstallExecuteSequence, and InstallUISequence tables to validate the following:

  • That the CostFinalize action occurs in any sequence table containing actions of the type Custom Action Type 35 or Custom Action Type 51.
  • That every Custom Action Type 35 comes after the CostFinalize action. in the sequence tables.
  • That every Custom Action Type 51 that has a foreign key to the Directory table in the Source column of the CustomAction table comes before the CostFinalize action in the sequence tables.

Note that ICE12 does not validate the formatted text in the Target column of the CustomAction table.

Result

ICE12 posts an error message if validation of the custom actions that set a directory property fails.

Example

ICE12 would post three errors for the example shown.

  • For CA1, Folder 'MyFolder' not found in Directory table
  • For CA2, Sequence '80' comes before CostFinalize in the InstallExecuteSequence table. It must come after (CF@100)
  • For CA3, Sequence '125' comes after CostFinalize in the InstallExecuteSequence table. It must come before (CF@100)

CustomAction Table (partial)

Action | Type | Source
CA1 | 35 | MyFolder
CA2 | 35 | WindowsFolder
CA3 | 51 | WindowsFolder

Directory Table

Directory | Directory_Parent | DefaultDir
TARGETDIR |  | SourceDir
WindowsFolder | TARGETDIR | WindowsFolder

InstallExecuteSequence Table (partial)

Action | Sequence
CostFinalize | 100
CA2 | 80
CA3 | 125

To fix the error for CA1 change its entry in its Source column in the CustomAction table to an existing entry in the Directory table or add MyFolder to the Directory table.

To fix the error for CA2, change its sequence in the InstallExecuteSequence table such that it comes after the CostFinalize action.

To fix the error for CA3, change its sequence in the InstallExecuteSequence table such that it comes before the CostFinalize action.

See Also

ICE Reference


ICE13

ICE13 validates that dialogs in sequence tables appear in the AdminUISequence, or InstallUISequence tables. Dialogs must not be listed in the InstallExecuteSequence, AdminExecuteSequence, or AdvtExecuteSequence tables.

Result

ICE13 posts an error message if a dialog appears in an execute sequence table.

Example

For the following example, ICE13 posts an error message stating that the 'WelcomeDialog' cannot be listed in the 'InstallExecuteSequence' table.

InstallExecuteSequence Table (partial)

Action
InstallFinalize
CostFinalize
WelcomeDialog

InstallUISequence Table (partial)

Action
CostFinalize
CostInitialize
BrowseDialog

Dialog Table (partial)

Dialog
BrowseDialog
WelcomeDialog

See Also

ICE Reference


ICE14

ICE14 validates the following for features:

  • That root parent features do not have the msidbFeatureAttributesFollowParent bit set in the Attributes column of the Feature table. A root feature does not have a parent.
  • That no feature has the same entry in the Feature and Feature_Parent columns of the Feature table. No feature can be its own parent.

Result

ICE14 posts an error message if it finds a root feature with the msidbFeatureAttributesFollowParent bit set or a feature with identical entries in the Feature and Feature_Parent columns of the Feature table.

Example

ICE14 would return the following errors for the following example:

  • The feature Sport has the same value in the Feature and Feature_Parent columns of the File table.
  • The root feature Sport has the msidbFeatureAttributesFollowParent bit set.

In the feature tree of this example, Sport is the root feature and a parent of the Swimming and Football features. Freestyle is a child feature of Swimming. TouchFootball is a child feature of Football.

Feature Table (partial)

Feature | Attributes | Feature_Parent
Sport | 4 | Sport
Swimming | 1 | Sport
Football | 4 | Sport
Freestyle | 1 | Swimming
TouchFootball | 4 | Football

See Also

ICE Reference


ICE15

ICE15 validates that content type and extension references in the MIME and Extension tables are reciprocal. The MIME table must reference a content type to an extension that the Extension table references back to the same content type.

Multiple extensions can reference the same MIME type, as long as the MIME type references back to one of the extensions. Multiple MIME types can reference the same extension, as long as the extension references back to one of the MIME types.

Note that whenever a MIME references an extension, that extension cannot have the MIME_ column in the Extension table set to Null.

Result

ICE15 posts an error if the content type and extension references are not reciprocal.

Example

ICE15 posts two error messages for the example shown:

  • The content type test/x-flaps in the MIME table references the extension tst, but the extension tst in the Extension table references flaps/x-flaps. This is not reciprocal.
  • The content type flaps/x-flaps references the extension flp, but that extension has a Null entry in the MIME_ column of the Extension table.

MIME Table (partial)

ContentType | Extension_
test/x-test | tst
flaps/x-flaps | flp

Extension Table (partial)

Extension | MIME_
tst | flaps/x-flaps
flp | NULL

See Also

ICE Reference


ICE16

ICE16 validates that the value of the ProductName property in the Property table is no greater than 63 characters in length.

The installer truncates ProductName values that are 31 to 63 characters in length to 31 characters. A longer name does not show when the registry key for DisplayName is set in the Uninstall for ARP.

Result

ICE16 posts an error message if the ProductName set in the Property table is longer than 63 characters.

See Also

ICE Reference


ICE17

ICE17 checks for the situations shown in the example at the end of this topic.

Result

ICE17 displays an error or warning message for each of the situations in the example. Samples of such messages are shown here.

ICE17 error or warning Description
PushButton: Button1 of Dialog: MyDialog does not have an event defined in the ControlEvent table.

Error

 There is a Pushbutton control that is not listed in the ControlEvent table.

Note: If ICE17 returns this error on a PushButton for which the Enable Control Attribute or the Visible Control Attribute is not set in the Attributes column of the Control table, check whether the control also has an entry in the ControlCondition table. The control can unexpectedly become enabled, or visible, if the value in the Condition column changes to True, Enable, or Show.
Bitmap: Bitmap1 of Control: Bitmap1 of Dialog: MyDialog is not in the Binary table.

Error

 There is a Bitmap control or Icon control, but the corresponding bitmap or icon is not listed in the Binary table. Add the bitmap or icon to the Binary table.

Note: If the ImageHandle bit is set in the Attributes column of the Control table the picture or icon can be created at run time and does not need to be in the Binary table.
RadioButtonGroup: RadioButton1 of Control: RadioButton1 of Dialog: MyDialog is not in the RadioButton table.

Warning

 There is a RadioButtonGroup control with values in the Property column and the Attribute column of the Control table; the Indirect bit is not set in the Attributes column. ICE17 posts a warning because the installer uses the property's value as a foreign key into the RadioButton table, but the value is missing from the primary key of that table.

If the Indirect bit is set, then the property listed for the control is not used as the property; instead, it is used as the name of the property that is actually used.

This warning can be ignored if the control is created at runtime. For example, the ListBox control for on the FilesInUse Dialog is only created at runtime if there are files in use during the installation.
ListBox: ListBox1 of Control: ListBox1 of Dialog: MyDialog is not in the ListBox table.

Warning

 There is a ListBox control with a value in the Property column of the Control table and for which the Indirect bit is not set in the Attributes column. ICE17 posts a warning because the installer uses the property's value as a foreign key into the ListBox table, but the value is missing from the primary key of that table.

If the Indirect bit is set, the control changes the value of a property having a name that is the value of the property associated with this control.

This warning can be ignored if the control is created at runtime. For example, the ListBox control for on the FilesInUse Dialog is only created at runtime if there are files in use during the installation.
ComboBox: ComboBox1 of Control: ComboBox1 of Dialog: ByDialog is not in the ComboBox table

Warning

 There is a ComboBox control with a value in the Property column of the Control table and for which the Indirect bit is not set in the Attributes column. ICE17 posts a warning because the installer uses the property's value as a foreign key into the ComboBox table, but the value is missing from the primary key of that table.

If the Indirect bit is set, the control changes the value of a property having a name that is the value of the property associated with this control.

This warning can be ignored if the control is created at runtime. For example, the ListBox control for on the FilesInUse Dialog is only created at runtime if there are files in use during the installation.
ListView: ListView1 of Control: ListView1 of Dialog: MyDialog is not in the ListView table.

Warning

 There is a ListView control with a value in the Property column of the Control table and for which the Indirect bit is not set in the Attributes column. ICE17 posts a warning because the installer uses the property's value as a foreign key into the ListView table, but the value is missing from the primary key of that table.

If the Indirect bit is set, the control changes the value of a property having a name that is the value of the property associated with this control.

This warning can be ignored if the control is created at runtime. For example, the ListBox control for on the FilesInUse Dialog is only created at runtime if there are files in use during the installation.
Bitmap: 'Bitmap2' for Control: 'Button2' of Dialog: 'MyDialog' not found in Binary table

Error

 There is a Pushbutton Control or Checkbox Control for which the Text column of the Control table does not contain a foreign key into the record of the Binary table containing the bitmap or icon.

Note: Use the ImageHandle bit if the bitmap or icon is to be loaded at runtime.
Bitmap: 'Bitmap3' for Control: 'RadioButton2' of Dialog: 'MyDialog' not found in Binary table

or

Icon: 'Icon1' for Control: 'RadioButton3' of Dialog: 'MyDialog' not found in Binary table

Error

 There is a RadioButtonGroup Control for which the Text column of the RadioButton table does not contain a foreign key into the record of the Binary table containing the bitmap or icon.

Note: Use the ImageHandle bit if the bitmap or icon is to be loaded at runtime.
Picture control: 'Button3' of Dialog: 'MyDIalog' has both the Icon and Bitmap attributes set

Error

 There is a PushButton, CheckBox, or RadioButtonGroup control with both the Icon bit or Bitmap bit set in the Attributes column of the Control table. You cannot set both attributes together.

Example

Control Table (partial)

Dialog_ | Control | Type | Attributes | Property | Text
MyDialog | Button1 | PushButton | 0 |  | OK
MyDialog | Bitmap1 | Bitmap | 0 |  | Bitmap1
MyDialog | RadioButton1 | RadioButtonGroup | 0 | RadioButton1 |
MyDialog | ListBox1 | ListBox | 0 | ListBox1 |
MyDialog | ComboBox1 | ComboBox | 0 | ComboBox1 |
MyDialog | ListView1 | ListView | 0 | ListView1 |
MyDialog | Button2 | Pushbutton | 262144 |  | Bitmap2
MyDialog | RadioButton2 | RadioButtonGroup | 262144 |  | Property2
MyDialog | RadioButton3 | RadioButtonGroup | 524288 |  | Property3
MyDialog | Button3 | Pushbutton | 786432 |  | Ambiguous1

RadioButton Table (partial)

Property_ | Order | Text
Property2 | 1 | Bitmap3
Property3 | 2 | Icon1

The following tables are empty:

  • ControlEvent Table
  • ListBox Table
  • ComboBox Table
  • ListView Table
  • Binary Table

See Also

ICE Reference


ICE18

ICE18 validates that any empty directories used as a key path for a component are listed in the CreateFolder table.

If the KeyPath column of the Component table is Null, this means that directory listed in the Directory_ column is the key path for that component. Because folders created by the installer are deleted when they become empty, this folder must be listed in the CreateFolder table to prevent the installer from attempting to install every time.

Do not make the SystemFolder directory the key path of a component. Because this folder is present on every operating system, the installer always detects the key path whether or not the component is present. In this case, the key path should be a file, registry entry, or ODBC data source.

When performing a validation ICE18 first checks whether the following are all true:

  • The KeyPath column of the Component table contains a Null value.
  • That there are no files listed for the component in the File table.
  • That there are no files for the component listed in the RemoveFile table and that the value in the DirProperty is the same as the Directory_ column of the Component table.
  • That there are no files for the component listed in the DuplicateFile table and that the value in the DestFolder is the same as the Directory_ column of the Component table.
  • That there are no files for the component listed in the MoveFile table and that the value in the DestFolder is the same as the Directory_ column of the Component table.

If these are all true then ICE18 validates the following:

  • That the Component_ column of the CreateFolder table has the same value as the Component column of the Component table.
  • That the Directory_ column of the CreateFolder table has the same value as the Directory_ column of the Component table.

Result

ICE18 posts an error message if the installation package specifies a directory as the key path for component that is not listed in the CreateFolder table.

See Also

ICE Reference


ICE19

ICE19 validates that advertised components reference a file in the KeyPath column of the Component table and that an advertised shortcut references a directory in this column.

ICE19 validates that advertised components or shortcuts have a ComponentId. Components in the PublishComponent table, which are not advertised in another table, are only checked to see whether they have a ComponentId.

Result

ICE19 posts an error message if the KeyPath column of the Component table does not reference a file in the case of an advertised component or a directory in the case of an advertised shortcut. ICE19 posts an error message if any advertised components or shortcuts do not have a ComponentId.

Example

ICE19 posts the following error messages for the example shown:

  • Extension flp references the component Comp1 which does not have a ComponentId specified in the Component table.
  • Extension exe references the component Comp4 which references a directory as its KeyPath. The KeyPath is Null in the Component table.
  • Shortcut Shortcut2 references the component Comp3 which references a Registry entry as the key path. The value of the Attributes column in the Component table is 4.

Component Table (partial)

Component | ComponentId | Attributes | KeyPath
Comp1 | NULL | 0 | File1
Comp2 | {00000002-0003-0000-0000-624474736554} | 0 | File2
Comp3 | {00000003-0003-0000-0000-624474736554} | 4 | Reg3
Comp4 | {00000004-0003-0000-0000-624474736554} | 0 | NULL

Extension Table (partial)

Extension | Component_
flp | Comp1
tst | Comp2
exe | Comp4

Shortcut Table (partial)

Shortcut | Component_ | Feature_
Shortcut1 | Comp4 | ProductFeature
Shortcut2 | Comp3 | ProductFeature

Feature Table (partial)

Feature
ProductFeature

Note If the extension flp and exe both reference the same component, the EXE or COM server that opens them must be the same. This EXE is normally the KeyPath for the Component. For OFFICE, the extensions doc and xls can not reference the same component because the same EXE doesn't open both extensions. You need winword.exe to open doc extensions and you need excel.exe to open xls extensions.

See Also

ICE Reference


ICE20

ICE20 validates the standard dialogs and dialog requirements of an installation package having an authored user interface. Installation packages with an authored user interface have a Dialog table and the LIMITUI property is not set.

ICE20 validates the following tables and requirements.

Standard dialog | Dialog requirements
FilesInUse Dialog A ListBox table.

A ListBox control with the Property column of the Control table set to FileInUseProcess.

A PushButton control with EndDialog entered into the Event column of the ControlEvent table and Ignore in the Argument column.

A PushButton control with EndDialog entered into the Event column of the ControlEvent table and Exit in the Argument column.

A PushButton control with EndDialog entered into the Event column of the ControlEvent table and Retry in the Argument column.

Error Dialog The Error Dialog Style bit must be set to specify the dialog, with any name, is an Error Dialog.

A Text control named ErrorText.

ErrorText in the Control_First column of the Dialog table.

A Pushbutton control, named A, with EndDialog in the Event column of the ControlEvent table and ErrorAbort in the Argument column.

A Pushbutton control, named C, with EndDialog in the Event column of the ControlEvent table and ErrorCancel in the Argument column.

A Pushbutton control, named I, with EndDialog in the Event column of the ControlEvent table and ErrorIgnore in the Argument column.

A Pushbutton control, named N, with EndDialog in the Event column of the ControlEvent table and ErrorNo in the Argument column.

A Pushbutton control, named O, with EndDialog in the Event column of the ControlEvent table and ErrorOk in the Argument column.

A Pushbutton control, named R, with EndDialog in the Event column of the ControlEvent table and ErrorRetry in the Argument column.

A Pushbutton control, named Y, with EndDialog in the Event column of the ControlEvent table and ErrorYes in the Argument column.

The width, height, and Y coordinates should be the same for all of the buttons. The X coordinates are determined by the installer.

Note: If a control named ErrorIcon exists, it must have Icon in the Type column of the Control table.
Exit Dialog | There must be either a Dialog or Custom Action in the AdminUISequence table and InstallUISequence table with a value -1 in the Sequence Column.
UserExit Dialog | There must be either a Dialog or Custom Action in the AdminUISequence table and InstallUISequence table with a value -2 in the Sequence Column.
FatalError Dialog | There must be either a Dialog or Custom Action in the AdminUISequence table and InstallUISequence table with a value -3 in the Sequence Column.

Result

ICE20 posts an error message if it cannot validate that the standard dialogs and requirements are present in the installation package.

See Also

ICE Reference


ICE21

ICE21 validates that every component in the Component table belongs to a feature. It uses the FeatureComponents table to check for this mapping.

Result

ICE21 posts an error message if the installation package contains a component that does not belong to a feature.

Example

For the following example, ICE21 posts an error message stating that the component Comp1 does not map to any feature.

Component Table (partial)

Component
Comp1
Comp2

FeatureComponents Table (partial)

Feature | Component
Feature1 | Comp2

See Also

ICE Reference


ICE22

ICE22 uses the FeatureComponents table to validate the mapping of features and components referenced in the PublishComponent table.

Result

ICE22 posts an error message if the features and components are mapped incorrectly in the PublishComponent table.

Example

For the following example ICE22 posts an error that {00000003-0004-0000-0000-624474732465} does not have the correct mapping for the Feature_ and Component_ columns.

PublishComponent Table (partial)

ComponentId | Feature_ | Component_
{00000002-0003-0000-0000-624474736554} | Feat1 | Comp1
{00000003-0004-0000-0000-624474732465} | Feat1 | Comp2

FeatureComponents Table (partial)

Feature_ | Component_
Feat1 | Comp1

See Also

ICE Reference


ICE23

ICE23 validates the control tab order for each dialog box.

ICE23 validates the following in the Dialog table and Control table:

  • That every record in the Dialog table specifies a control in the Control_First column that exists in the dialog box specified by the Dialog column.
  • That every record in the Control table specifies a control in the Control_Next column that is on the same dialog as the control listed in the Control column, or Control_Next contains the Null value.
  • That following the Control_Next entries from control to control in the Control table makes a single, closed, loop that comes back to the initial control. Not every control needs to be in the loop, but the loop must pass through every control that has an entry in the Control_Next column.

Result

ICE23 posts an error message if the tab order of controls does not form a single closed loop in the dialog box.

Example

ICE23 would post the following error messages for the example shown.

  • Dialog1 has no Control_First.
  • Control_First of dialog Dialog2 refers to nonexistent control ControlX.
  • Dialog3 has dead-end tab order at control ControlB.
  • Dialog4 has malformed tab order at control ControlC
  • Dialog5 has malformed tab order at control ControlC.
  • Control_Next of control Dialog6.ControlC links to unknown control.

Dialog Table (partial)

Dialog | Control_First
Dialog1 |
Dialog2 | ControlX
Dialog3 | ControlA
Dialog4 | ControlA
Dialog5 | ControlA

Control Table (partial)

Dialog | Control | Control_Next
Dialog1 | ControlA |
Dialog1 | ControlB | ControlA
Dialog2 | ControlA | ControlB
Dialog2 | ControlB | ControlA
Dialog3 | ControlA | ControlB
Dialog3 | ControlB |
Dialog4 | ControlA | ControlB
Dialog4 | ControlB | ControlC
Dialog4 | ControlC | ControlB
Dialog5 | ControlA | ControlB
Dialog5 | ControlB | ControlC
Dialog5 | ControlC | ControlA
Dialog5 | ControlD | ControlA
Dialog6 | ControlA | ControlB
Dialog6 | ControlB | ControlC
Dialog6 | ControlC | ControlX
Dialog6 | ControlD | ControlA

To fix these errors note the following in the above tables and make the indicated changes.

Not every row in the Dialog table has a control specified in the Control_First column. Change the Control_First column of the Dialog1 record in the Dialog table to a control that exists in Dialog1.

Not every row in the Dialog table has a control specified in the Control_First column that exists on the dialog box. Change the Control_First column of the Dialog2 to a control that exists in Dialog2.

Following the Control_Next entries in the Control table from control to control does not make a closed loop in every case. Change the Control_Next column for ControlB in Dialog3 to ControlA.

Following the Control_Next entries in the Control table from control to control does not lead back to the initial control in every case. Change the Control_Next column for ControlC in Dialog4 to refer to ControlA.

Following the Control_Next entries in the Control table from control to control does not pass through every control in the dialog box having an entry in the Control_Next column. Change the Control_Next column for ControlC in Dialog5 to ControlD.

Control_Next does not refer to a valid control that is in the same dialog as the control listed in the Control column. Change the Control_Next column for ControlC in Dialog6 to refer to ControlD.

See Also

ICE Reference


ICE24

ICE24 validates the following properties in the Property table:

  • That the ProductCode Property is a valid GUID data type.
  • That the ProductVersion Property is a valid Version data type.
  • That the ProductLanguage Property is a valid Language data type.

Result

ICE24 posts an error message if any of these properties are not in the form of a valid data type.

See Also

ICE Reference


ICE25

ICE25 validates that a .msi file satisfies all of its internal merge module dependencies and exclusions. ICE validates the following:

  • That all merge module dependencies indicated in the .msi file's ModuleDependency table are satisfied by at least one merge module listed in the ModuleSignature table.
  • That none of the excluded merge modules in the ModuleExclusion table are incompatible with the merge modules listed in the ModuleSignature table.

Result

ICE25 posts an error message if .msi file has previously been merged with an incompatible merge module or if it has not been merged with a necessary merge module.

Example

ICE25 posts the following errors for the example shown.

Dependency failure: Need ModuleX@0 v2.0
Module ModuleB@1033 v1.0 is excluded.

ModuleSignature Table

ModuleID | Language | Version
ModuleA | 0 | 1.0
ModuleB | 1033 | 1.0

ModuleDependency Table

ModuleID | ModuleLanguage | RequiredID | RequiredLanguage | RequiredVersion
ModuleA | 0 | ModuleX | 0 | 2.0

ModuleExclusion Table

ModuleID | ModuleLanguage | ExcludedID | ExcludedLanguage | ExcludedMinVersion | ExcludedMaxVersion
ModuleA | 0 | ModuleB | 1033 |  |

See Also

ICE Reference


ICE26

ICE26 validates that each of the following sequence tables contains the actions that are required by the table and does not contain any actions disallowed in the table:

  • AdminUISequence table
  • AdminExecuteSequence table
  • InstallUISequence table
  • InstallExecuteSequence table

Result

ICE26 posts an error message if the installation package has a sequence table that lacks a required action or that contains an action that is disallowed for the table.

Example

ICE26 error | Description
Action: 'Action1' is required in the InstallExecuteSequence Sequence table. | A required action is missing from the indicated sequence table. See the template.msi or the suggested sequence tables in Using a Sequence Table.
Action: 'Action2' is prohibited in the InstallExecuteSequence Sequence table. | This action cannot be in the indicated sequence table. Remove this action from the sequence table.

See Also

ICE Reference


ICE27

ICE27 validates the sequence tables of an installation package for valid actions, action sequence restrictions, and organization in Search, Costing, Selection, and Execution sections.

The ICE27 custom action validates the following:

  • That the actions listed in the Action column of the sequence tables are a standard actions, a custom action listed in the CustomAction table, or a dialog box listed in the Dialog table.
  • That actions subject to sequencing restrictions are in the correct relative order to each other in the action sequence. Sequencing restrictions result when one action is dependent on another.
  • That actions restricted to a particular section of the sequence are located where they belong. ICE27 validates the following organization of the sequence tables. Note that not every sequence table has every section. See the suggested sequence tables in Using a Sequence Table.
Sequence table section | Range in action sequence | Actions belonging to section
Search | {start} to CostInitialize | Actions that search for existing applications. AppSearch CCPSearch
Costing | CostInitialize to CostFinalize action | Actions that do file costing. CostInitialize FileCost CostFinalize
Selection | CostFinalize to InstallValidate | Actions that set folders or feature states. SetODBCFolders action
Execution | InstallValidate to InstallFinalize | Script actions, such as Registration, Publication, Installation (where you copy files). Note the InstallFinalize action must be in the table if and only if there are actions in the Execution section.
PostExecution | InstallFinalize to {end} | RemoveExistingProducts

ICE27 validates the following tables:

  • AdvtExecuteSequence
  • AdminUISequence
  • AdminExecuteSequence
  • InstallUISequence
  • InstallExecuteSequence

Result

ICE27 posts an error message if there are sequence tables in the package with invalid action sequencing or organization.

Example

ICE27 error | Description
Unknown action: 'Action1' of InstallExecuteSequnence table. Not a standard action and not found in CustomAction or Dialog tables | There is an action listed in the sequence table indicated that is not a standard actions, a custom action listed in the CustomAction table, or a dialog box listed in the Dialog table.
'Action2' in InstallExecute table in wrong place. Current: Search, Correct: Costing There is an action in a sequence table that is incorrectly placed with respect to the sequence number in the Sequence column.

"Current" indicates the current placement of the action in the Search, Costing, Selection, or Execution sections of the indicated sequence table.

"Correct" indicates in which section the action belongs.

To fix this error, change the sequence number of the action to inside the correct section. Note that some action can be located in more than one section.

'InstallFinalize' Action in InstallExecuteSequence table can only be called when script operations exist to be executed There is an InstallFinalize action in a sequence table that does not contain any script operations in the Execution section of the table.

Add actions to the Execution section or remove the InstallFinalize action from the table.
InstallFinalize must be called in InstallExecuteSequence table as script operations exist to be executed There is a sequence table containing actions in the Execution section that does not include the InstallFinalize action.

Add the InstallFinalize action to this sequence table and give it the greatest sequence number to place it last in the action sequence.
Action: 'Action3' in InstallExecuteSequence table must come before the 'Action5' action. Current seq#: 1200. Dependent seq#: 1100 There is an action in the indicated sequence table that is sequenced after a dependent action.

Change the sequence number on the dependent action so that it comes before the action.
Action: 'Action4' in InstallExecuteSequence table must come after the 'Action6' action. There is an action in the indicated sequence table that is sequenced before an action that it is dependent upon.

Change the sequence number on the action so that it comes after its dependent action.

See Also

ICE Reference


ICE28

ICE28 is commonly used to validate that the ForceReboot action is placed before or after, and never within, a specific group of actions in the action sequence tables. See the ForceReboot action topic to determine the actions that comprise this group.

ICE28 validates actions in the following sequence tables.

AdminUISequence table

AdminExecuteSequence table

InstallUISequence table

InstallExecuteSequence table

Result

ICE28 posts an error message if ForceReboot is sequenced within the specified action group.

Example

For the example shown, ICE28 posts the following error message.

Action: 'ForceReboot' of table InstallExecuteSequence is not permitted in the range 5 to 15 because it cannot separate a set of actions contained in this range.

InstallExecuteSequence Table

Action | Sequence
ForceReboot | 10
RegisterMIMEInfo | 5
RegisterProgIdInfo | 15

The sequence number of 10 given to ForceReboot breaks generates the error, because it comes between the sequence numbers of RegisterMIMEInfo and RegisterProgIdInfo.

See Also

ICE Reference


ICE29

ICE29 validates that truncated stream names remain unique. Any table having a Binary or Object column is validated. See the Binary column data type.

Handling of streams by the Win32 OLE structured storage implementation limits stream names. See OLE Limitations on Streams. The installer can compress stream names up to 62 characters in length. Names longer than this are truncated.

See Also

ICE Reference


ICE30

ICE30 validates that the installation of components containing the same file never installs the file more than once in the same directory.

ICE30 goes to every component in the Component table and then determines the component's target directory from the Directory table. It then checks to see which of these components install to the same target directory. Finally, it uses the File table to verify that none of the files in these components have the same name.

ICE30 checks both long file names (LFN) and short file names (SFN).

ICE30 does not evaluate properties in the resolution of directories because these properties can change at runtime and alter the directory resolution scheme. This means ICE30 can detect file collisions due to directories with the same property in their paths, but does not detect collisions resulting from two properties having the same value.

Result

ICE30 posts an error message for each pair of components that installs the same file to the same directory.

Example

The example shown returns each of the following errors twice.

ICE29 error or warning Description
ERROR: The target file 'README.1st' is installed in 'TARGETDIR\PRODUCT' by two different components on an SFN system: 'Component1' and 'Component2'. This breaks component reference counting. Component1 and Component2 both have a file named 'READEME.1st'.

When using short file names, the installer installs both Dir1 and Dir2 to the same directory, TARGETDIR\PRODUCT.

ICE30 generate two errors, one for each file. In an authoring environment that displays error locations, the first error is at one file's entry in the File Table, and the second at the location of the other file.

ERROR: Installation of a conditionalized component would cause the target file 'README.1st' to be installed in 'TARGETDIR\COMMON TOOLS' by two different components on an LFN system: 'Component3' and 'Component4'. This would break component reference counting. Component4 has an entry in the Condition column of the Component table and Component3 does not.

If VersionNT is True, Component4 is installed, and there a collision with the Readme.1st always installed by Component3.

ICE30 generates 4 errors, one pair for SFN, one for LFN.
WARNING: The target file 'README.1st' might be installed in 'TARGETDIR\COMMON TOOLS' by two different conditionalized components on an SFN system: 'Component4' and 'Component5'. If the conditions are not mutually exclusive, this will break the component reference counting system. Because Component4 and Component5 both have entries in the Condition column of the Component table this file collision may not occur.

ICE30 only posts a warning because the conditions must be determined at the time of the installation.

ICE30 generates 4 warnings, one pair for SFN, one for LFN.

Component Table (partial)

Component | Directory | Condition
Component1 | Dir1 |
Component2 | Dir2 |
Component3 | Dir3 |
Component4 | Dir3 | VersionNT
Component5 | Dir3 | Version9X

Directory Table

Directory | Parent_Directory | DefaultDir
SOURCEDIR |  | TARGETDIR
Dir1 | SOURCEDIR | Product|Component1 Product:.
Dir2 | SOURCEDIR | Product:.
Dir3 | SOURCEDIR | Common|Common Tools:

File Table (partial)

File | Component_ | FileName
File1 | Component1 | README.1st
File2 | Component2 | README.1st
File3 | Component3 | README.1st
File4 | Component4 | README.1st
File5 | Component5 | README.1st

See Also

ICE Reference


ICE31

ICE31 validates any predefined font styles used in controls that display text. It also validates that the DefaultUIFont property refers to a valid font style.

Controls can have a predefined font style as described in Adding Controls and Text. You can set the font style by putting the name of a style in the form {\style} at the start of the text string which is to appear in the control. Where style is a style name listed in the TextStyle field of the TextStyle table. A base text style can be assigned to any control by supplying {&style} at the start of the text string. This style is used if no other style is set by the text string. A text string may contain both style and base style specifications.

ICE31 checks the Text column for each control in the Control Table to verifies that a valid entry exist in the TextStyle table.

ICE31 ignores the ScrollableText Control.

Results

ICE31 posts an error message for undefined styles, style names that are too long, a missing TextStyle table, and style tags with no closing brace.

ICE31 posts a warning if the style tag is not at the beginning of the line, or if a control has multiple style tags.

Example

ICE31 posts the following errors for the example shown

  • Control DialogB.Control1 uses undefined TextStyle BadStyle.
  • Control DialogB.Control2 uses undefined TextStyle BadStyle.
  • Control DialogB.Control6 is missing closing brace in text style.
  • Control DialogB.Control3 specifies a text style that is too long to be valid.

ICE31 posts the following warning for the example shown.

  • Text Style tag in DialogB.Control4 has no effect. Do you really want it to appear as text?

Control Table (partial)

Dialog | Control | Text
DialogA | Control0 | {\OKStyle}This is the text to display.
DialogA | Control1 | {&OKStyle}This is the text to display.
DialogB | Control1 | {&BadStyle}This is the text to display.
DialogB | Control2 | {\BadStyle}This is the text to display.
DialogB | Control3 | {&Style that is over 72 chars and therefore cannot possibly be a style even if somehow you did manage to get it in the TextStyle table}This is the text to display.
DialogB | Control4 | Warning {\OKStyle}This is the text to display.
DialogB | Control5 | {\OKStyle}{&OKStyle}This is the text to display.
DialogB | Control6 | {\OKStyle This is the text to display.

TextStyle table (partial)

TextStyle
OkStyle

See Also

ICE Reference


ICE32

ICE32 validates that keys and foreign keys in the .msi file are of the same size and column definition types. This ICE custom action makes the comparison using the _Validation table and using the definition types that are returned by MsiViewGetColumnInfo. For more information, see Column Definition Format.

Result

ICE32 posts errors if the .msi file contains any foreign keys to keys of a different column length or column data type.

Example

ICE32 posts two errors for the example shown:

  • There is a foreign key and key defined that differ in size.
  • There is a foreign key and key defined that differ in their definition type.

_Validation Table (partial)

Table | Column | KeyTable | KeyColumn
File | Version | File | 1
Flap | Column8 | Flap | 1

Column Definitions (partial)

Table | Column | Type | Size
File | File | s | 72
File | Version | S | 32
Flap | Column1 | i | 2
Flap | Column8 | S | 32

The Version column of the File table can be a foreign key to another file in the File table. This occurs with companion files. However, the Version column only allows a string length 32, whereas the File column allows a string length 72. To fix this error change the string lengths to match.

There is a foreign key and key defined that differ in their definition types. Column8 of the Flap Table is listed as a foreign key to Column1. Column8 is a string column and Column1 is an integer column. The foreign key and key pairs must be defined so that their data types match.

See Also

ICE Reference


ICE33

ICE33 validates that the all the entries in the Registry table belong in that table. It issues a warning for each Registry table entry that should be moved and suggests the appropriate table. ICE33 posts warnings for any entries that register Classes, Filename Extensions, ProgIDs, Shell Verbs, Remote Server AppIDs, MIME types, or Typelibs.

It is strongly recommended that any Registry table entries generating a warning be moved to the table suggested by the warning. It can make the database easier to author and maintain and is commonly necessary to support advertisement and install-on-demand.

Extensions, ProgIds, Verbs, and MIME types must be registered through their respective Extension, ProgId, Verb, MIME tables to support advertisement and install-on-demand. Entries in the Registry table are not written to the registry until the component controlling the value is installed to run Locally or to Run From Source. This precludes the advertisement of components registered through the Registry table. It also precludes install-on-demand for any feature or product requiring the component because advertisement is the only way install-on-demand is available through the Windows Shell.

For Windows 2000, COM Classes must be registered through the Class table to advertise CLSID Contexts and for install-on-demand.

Note that the tables available cannot handle all possible COM registration. In these cases an author should enter as much information as possible into to the individual tables and the remaining information into the Registry table. A common authoring error that must be avoided in this case is that of duplicating an entry in both a COM table and in the Registry table.

It is easier to manage registry keys if they are listed in the appropriate tables rather than being mixed together into the Registry tables. The values in the Typelib and AppId tables are registered when the component controlling the value is installed to run Locally or From Source. These tables are provided for the convenience of authors.

See Also

ICE Reference


ICE34

ICE34 validates that each radio button on every RadioButtonGroup Control has a property in the Property column of the RadioButton table that specifies its radio button group. ICE34 validates that this property exists and is set to a default value in the Property table which is equal to one of the group's radio button values in the Value column of the RadioButton table.

A radio button group must have a default for users to be able to select a choice using the TAB key. This is required for proper user accessibility.

ICE34 reports missing tables.

Result

ICE34 post an error message if there is a radio button that specifies an invalid property.

Example

ICE34 reports the following errors for the example shown.

ICE34 error | Description
Control DialogA.Control2 must have a property because it is of type RadioButtonGroup. | There is a RadioButtonGroup control, without the Indirect control bit set in the Attributes column of the Control table, that does not have a property listed in the Property column.
Maybe is not a valid default value for the RadioButtonGroup using property Property3. The value must be listed as an option in the RadioButtonGroup table. | There is a default value for a property specified in the Value column of the Property table that is not one of the values for the radio button group specified in the Value column of the RadioButton table.
Property PropertyB must be defined because it is an indirect property of a RadioButtonGroup control DialogA.Control4 | The property referenced by this RadioButton group is an indirect property, and the value of the indirect property is not one of the choices for the RadioButton group.
Maybe is not a valid default value for the property PropertyA. The property is an indirect RadioButtonGroup property of control DialogA.Control5 (via property Property5). | The value of the indirect property referenced via the control is not one of the default values for that RadioButtonGroup.

Control Table (partial)

Dialog | Control | Type | Attributes | Property
DialogA | Control1 | RadioButtonGroup | 0 | Property1
DialogA | Control2 | RadioButtonGroup | 0 |
DialogA | Control3 | RadioButtonGroup | 0 | Property3
DialogA | Control4 | RadioButtonGroup | 8 | Property4
DialogA | Control5 | RadioButtonGroup | 8 | Property5

Property Table (partial)

Value
Yes
Maybe
PropertyB
PropertyA
Maybe

RadioButton Table (partial)

Property | Order | Value
Property1 | 1 | Yes
Property1 | 2 | Now
Property2 | 1 | Yes
Property2 | 2 | No
Property3 | 1 | Yes
Property3 | 2 | No
Property4 | 1 | Yes
Property4 | 2 | No
PropertyA | 1 | Yes
PropertyA | 2 | No
PropertyB | 1 | Yes
PropertyB | 2 | No

To fix the errors reported by this ICE, check the following:

  • That every RadioButton control entry without the indirect attribute set has a property listed in the Property column:
  • That every such property has at least one corresponding entry in the RadioButton table.
  • That every such property is defined in the Property table, with a value that is one of the choices from the RadioButton table.
  • That every property referenced in the Property column of a RadioButton control with the indirect attribute set is defined in the Property table.

See Also

ICE Reference


ICE35

ICE35 validates that components containing compressed files stored in a cabinet file are not set to run from source.

ICE35 queries the Cabinet column of the Media table to determine which files are compressed and stored in a cabinet file. It queries the File table to determine which components contain these files. Finally, it checks the Component table to determine whether the run-from-source bits are set in the Attributes column.

Result

ICE35 posts an error message if there is a compressed file stored in a cabinet file belonging to a component with the msidbComponentAttributesSourceOnly bit set in the Attributes column of the Component table.

ICE35 posts warning message if there is a compressed file stored in a cabinet file belonging to a component with the msidbComponentAttributesOptional bit set in the Attributes column of the Component table.

If multiple files in a component are in a cabinet file, ICE35 reports errors for each file that has the run from source bit set.

Example

ICE35 reports the following errors and warnings for the example shown.

ICE35 Error Description
ERROR: Component Component3 cannot be Run From Source only, because its member file 'File3' is compressed. There is a compressed file stored in a cabinet file and this file belongs to a component with the SourceOnly bit set in the Attributes column of the Component table.

To fix this error change the lower 2 bits of Component2's Attributes value to "00", meaning Local only, or remove File4 from the CAB file.
ERROR: Component Component3 cannot be Run From Source only, because its member file 'File3' is compressed. There is a compressed file stored in a cabinet file and this file belongs to a component with the SourceOnly bit set in the Attributes column of the Component table.

Because the files in a component do not all have to originate from the same media, ICE35 reports errors for each file in the component that is in a cabinet.

To fix this error change the lower 2 bits of Component2's Attributes value to "00", meaning Local only, or remove File4 from the CAB file.

Media Table (partial)

DiskID | LastSequence | Cabinet
1 | 2 |
2 | 4 | One.cab
3 | 5 | #Two.cab

File Table (partial)

File | Component_ | Sequence
File1 | Component1 | 1
File2 | Component2 | 2
File3 | Component2 | 3
File4 | Component3 | 4
File5 | Component3 | 5

Component Table (partial)

Component | Attributes
Component1 | 0
Component2 | 2
Component3 | 1

Shortcut Table (partial)

Shortcut | Icon_
Shortcut1 | Icon2

Note that that files can also be marked as compressed using the Word Count Summary Property of the Summary Information stream.

See Also

ICE Reference


ICE36

ICE36 validates that every icon in the Icon table is listed at least once in the Class, ProgId, or Shortcut tables.

During advertisement, the installer installs all the icons listed in the Icon table on the user's machine. Having unused icons in the icon table does not prevent the installation from running, however it does unnecessarily increase the size of the .msi file and the time and space required to advertise a feature.

If an icon is not referenced in a table and there is no UI provided to create a reference at runtime, you should remove the Icon to achieve better performance.

Result

ICE36 posts a message if there is a icon in the Icon table that is not referenced in the Class, ProgId, or Shortcut tables and if there is no UI provided to create such a reference at runtime.

Example

ICE36 reports the following error for the example shown.

Icon Bloat. Icon Icon4 is not used in the Class, Shortcut, or ProgID table. This adversely affects performance.

Icon Table (partial)

Name | Data
Icon1 | Control1
Icon2 | Control2
Icon3 | Control3
Icon4 | Control4

ProgID Table (partial)

ProgID
Property1

Class Table (partial)

CLSID
{3E469ABA-3644-11d2-8892-00A0C981B015}

Shortcut Table (partial)

Shortcut | Icon_
Shortcut1 | Icon2

See Also

ICE Reference


ICE38

ICE38 validates that every component being installed under the current user's profile also specifies a registry key under the HKEY_CURRENT_USER root in the KeyPath column of the Component table.

Result

ICE38 posts an error if a component installed under the user's profile does not specify a HKCU registry key.

Example

ICE38 reports the following errors for the sample shown.

ICE38 error | Description
Component Component1 installs to user profile. It must use a registry key under HKCU as its KeyPath, not a file. | The value of the attributes column of Component1 is 0, meaning that the component must use a file as its KeyPath. This causes difficulties when multiple users install the component on the same machine. To fix this error on Component1, set the RegistryKeyPath bit in the Attributes column of the Component table and change the entry in the KeyPath column to a value listed in the Registry column of the Registry table.
Component Component2 installs to user profile. It must use a registry key under HKCU as its KeyPath. The KeyPath is currently NULL. | Component2 has the RegistryKeyPath bit set in the Attributes column of the Component table. The KeyPath field must therefore contain a key to the Registry column of the Registry Table but the KeyPath column is Null. To fix this error, change the KeyPath value to a valid entry into the Registry table.
Component Component3 installs to user profile. It's KeyPath registry key must fall under HKCU. | Component3 has the RegistryKeyPath bit set in the Attributes column of the Component table but the root of the registry entry specified in the Root column of the Registry table specifies HKEY_LOCAL_MACHINE rather than HKEY_CURRENT_USER. To fix this error, use a valid registry entry under HKEY_LOCAL_MACHINE as the KeyPath for this component or change the value in the Root column of the Registry table to -1 or 1.
The KeyPath registry entry for component Component4 does not exist. | Component4 has the RegistryKeyPath bit set in the Attributes column of the Component table but the entry in the KeyPath column does not exist in the Registry Table. To fix this error, add an entry for Reg4 to the Registry table that is a under HKEY_CURRENT_USER.
The Registry Entry Reg5 is set as the KeyPath for component Component5, but that registry entry doesn't belong to Component5. | The Registry entry referenced in the KeyPath column of the component was found and lies under the HKCU tree, but the registry entry's Component_ column does not refer back to the same component that listed it as the KeyPath. This means that the registry entry used as the KeyPath of the component would only be created when some other component was installed. To fix this error change the KeyPath value to refer to a registry entry that belongs to the component, or change the registry entry to belong to the component using it as a KeyPath.

Directory Table (partial)

Directory | Directory_Parent | DefaultDir
Dir1 |  | StartMenuFolder
Dir2 |  | DesktopFolder
Dir3 | Dir3 | AppData
Dir4 | Dir3 | SubDir

Component Table (partial)

Component | Directory_ | Attributes | KeyPath
Component1 | Dir1 | 0 | File1
Component2 | Dir2 | 4 |
Component3 | Dir3 | 4 | Reg3
Component4 | Dir4 | 4 | Reg4
Component5 | Dir5 | 4 | Reg5

Registry Table (partial)

Registry | Root | Value | Component_
Reg3 | 2 |  | Component3
Reg5 | 0 |  | Component4

See Also

ICE Reference


ICE39

ICE39 validates the Summary Information Stream of the database.

ICE39 checks the format of the Word Count Summary Property, Page Count Summary Property, Template Summary Property, Revision Number Summary Property, Create Time/Date Summary Property, Last Saved Time/Date Summary Property, and Last Printed Summary Property.

If the Word Count Summary Property specifies that the source is compressed, ICE39 posts a warning if any files are also marked as compressed in the Attributes column of the File table. See Using Cabinets and Compressed Sources.

See Also

ICE Reference


ICE40

ICE40 does miscellaneous validation.

Result

ICE40 posts warnings on the following:

  • The .msi file is missing the Error table.
  • The REINSTALLMODE property has been overridden.
  • The RemoveIniFile table has a Delete Tag entry with no value.

Example

Property Table

Property | Value
REINSTALLMODE | A

RemoveIniFile Table

RemoveIniFile | Action | Value
REINSTALLMODE | 4 |

Results

ICE40 would report the following errors:

ICE40 error | Description
REINSTALLMODE is defined in the Property table. This may cause difficulties. | Defining the REINSTALLMODE property in .msi file can lead to unexpected behavior. To fix this error, don't define this property.
RemoveIniFile entry Remove1 must have a value, because the Action is "Delete Tag" (4). | There is a Delete Tag action in the in the RemoveIniFile column of the RemoveIniFile table without specifying a tag to delete in the Value column.
Error Table is missing. Only numerical error messages will be generated. | The Error table is missing from the .msi file. This means that the installer is only capable of displaying numeric error codes to the user at run time. To fix this error, add an Error table to the installation package and author formatting templates in the Message column for error messages.

See Also

ICE Reference


ICE41

ICE41 validates that the entries in the Class and Extension tables refer to entries in the Component table that implement the class object or extension of the component.

Result

ICE41 posts an error if there is a feature that does not contain the component implementing the class object or extension.

Example

ICE41 reports the following errors for the example shown.

ICE41 error | Description
Class {00000000-0000-0000-0000-0000000000000} references feature Feature2 and component Component1, but the that Component is not associated with that Feature in the FeatureComponents table. | There is a feature that does not contain the component implementing the class object. This means that the installer does not install the component with the feature and that advertising may not work as expected. To fix this error, change the entry in the Feature_ column of the Class table entry to reference a feature that installs component listed in the Component_ column or change the feature and component associated in the FeatureComponents table.
Extension .yip references feature Feature1 and component Component2, but the that Component is not associated with that Feature in the FeatureComponents table. | There is a feature that does not contain the component implementing the extension. This means that the installer does not install the component with the feature and that advertising may not work as expected. To fix this error, change the entry in the Feature_ column of the Extension table entry to reference a feature that installs the component listed in the Component_ column or change the feature and component associated in the FeatureComponents table.

FeatureComponents Table (partial)

Feature_
Feature1
Feature2

Class Table (partial)

CLSID | Component_ | Feature_
{00000000-0000-0000-0000-000000000000} | Component1 | Feature2

Class Table (partial)

Extension | Component_ | Feature_
.yip | Component2 | Feature1

See Also

ICE Reference


ICE42

ICE42 validates that InProc servers are not linked to EXE files in the Class table. It also validates that only LocalServer and LocalServer32 classes have arguments and DefInProc values.

Result

ICE42 posts an error if there are InProc servers linked to EXE files in the Class table.

Example

ICE42 would report the following errors for the example shown.

ICE42 error | Description
CLSID '{GUID1}' is an InProc server, but the implementing component 'Component1' has an EXE ('test.exe') as its KeyFile. | There is an executable file specified as an InProc server. EXE files cannot be InProc servers.
CLSID '{GUID1}' in context 'InProcServer32' has an argument. Only LocalServer contexts can have arguments. | To fix this error, remove the argument.
CLSID '{GUID1}' in context 'InProcServer32' species a default InProc value. Only LocalServer contexts can have default InProc values. | There is an object with a default InProc value that is not an object operating in the LocalServer or LocalServer32 contexts. To fix this error, remove the DeflnProc value or change the context of the class.

Class Table (partial)

CLSID | Context | Component_ | DefInProcHandler | Argument
{GUID1} | InProcServer32 | Component1 | InProcServer | Arg

Component Table (partial)

Component | KeyPath
Component1 | File1

File Table (partial)

File | Filename
File1 | test.exe

See Also

ICE Reference


ICE43

ICE43 validates that shortcuts that do not reference a feature as their Target (non-advertised shortcuts) are in components having a HKCU registry entry as their key path.

Result

ICE43 posts an error message if a non-advertised shortcut is in a component that does not have a HKCU registry entry as its key path.

Example

ICE43 would report the following errors for the example shown.

ICE43 error | Description
Component Component1 has non-advertised shortcuts. It must use a registry key under HKCU as its KeyPath, not a file. | The attributes column of Component1 is 0, meaning that the component uses a file as its KeyPath. This causes non-advertised shortcuts in this component to be installed for the first user on the machine ONLY. Users who install the component later do not see the shortcuts because the component appear to the installer as already existing on the machine. To fix this error, set the RegistryKeyPath bit of the attributes to switch the Component to a Registry entry, then change the KeyPath value to a valid entry in the Registry table.
Component Component2 has non-advertised shortcuts. It must use a registry key under HKCU as its KeyPath. The KeyPath is currently NULL. | The Attributes column is set to use the registry, but the KeyPath is NULL. The KeyPath must refer to an entry in the Registry Table. To fix this error, change the KeyPath value to a valid entry in the Registry table.
Component Component3 has non-advertised shortcuts. Its KeyPath registry key must fall under HKCU. | The Attributes column is set to use the registry, but the referenced registry entry is not under HKCU. To fix this error, either switch to a different registry entry as the KeyPath for this component, or change the Root value of the Registry entry to either -1 or 1.
The KeyPath registry entry for component Component4 does not exist. | The Registry entry referenced in the KeyPath column of the component is not in the Registry Table. To fix this error, create an entry.
The Registry Entry Reg5 is set as the KeyPath for component Component5, but that registry entry doesn't belong to Component5. | There is a Registry entry referenced in the KeyPath column of the component that lies under the HKCU tree, but the registry entry's Component_ column does not refer back to the same component that listed it as the KeyPath. This means that the registry entry used as the KeyPath of the component is only created if some other component was installed. To fix this error, change the KeyPath value to refer to a registry entry that belongs to the component or change the registry entry to belong to the component using it as a KeyPath.

Component Table (partial)

Component | Attributes | KeyPath
Component1 | 0 | File1
Component2 | 4 |
Component3 | 4 | Reg3
Component4 | 4 | Reg4
Component5 | 4 | Reg5

Registry Table (partial)

Registry | Root | Value | Component_
Reg3 | 2 |  | Component3
Reg5 | 0 |  | Component4

See Also

ICE Reference


ICE44

ICE44 validates that the NewDialog, SpawnDialog, and SpawnWaitDialog ControlEvents reference valid dialog boxes in the Dialog table.

Result

ICE44 posts an error message if there is a dialog control event that does not reference a dialog box listed in the Dialog table.

Example

ICE44 would report the following errors for the example shown.

ICE44 error | Description
Control Event for Control 'Dialog1'.'Control1' is of type SpawnDialog, but its argument Dialog2 is not a valid entry in the Dialog Table. | There is a SpawnDialog, SpawnWaitDialog, or NewDialog actions that has an argument that does not refer to a dialog box in the Dialog table. To fix this error, add an argument that is a key in the Dialog Table.

Dialog Table (partial)

Dialog | Title
Dialog1 |

ControlEvent Table (partial)

Dialog_ | Control_ | Type | Argument
Dialog1 | Control1 | SpawnDialog | Dialog2

See Also

ICE Reference


ICE45

ICE45 validates that bit field columns in the database do not set any reserved bits to 1.

Reserved bits provide no functionality in current versions of the installer, but might in future versions. They should be set to 0 to be compatible with future versions of Windows Installer.

Result

ICE45 posts an error message if any of the following tables contains a bit field with a reserved bit set to a value of 1.

  • BBControl table
  • Dialog table
  • Feature table
  • File table
  • MoveFile table
  • ModuleConfiguration table
  • ODBCDataSource table
  • Patch table
  • RemoveFile table
  • ServiceControl table
  • ServiceInstall table
  • TextStyle table

ICE45 posts one of two warning messages if the Control Table contains a bit field with a reserved bit set to a value of 1.

Example

ICE45 reports the following error for the example shown.

Row 'File1' in table 'File' has bits set in the 'Attributes'
    column that are reserved. They must be 0 to ensure
    compatibility with future installer versions.

ICE45 reports the following warning for the example shown.

Row 'Dialog1.Edit2' in table 'Control' has bits set in the 'Attribute'
    column that are reserved. They should be 0 to ensure compatability
    with future installer versions.

ICE45 reports the following warning if the Page Count Summary Property in the Summary Information Stream is 100 because the Password Control Attribute (2097152) is not used with Windows Installer version 1.0, but is used with version 1.1.

Row 'Dialog1.Edit1' in table 'Control' has bits set in the 'Attribute'
    column that are not used in the schema of the package, but are
    used in a later schema. Your package can run on systems where this
    attribute has no effect.

File Table (partial)

File | Attributes
File1 | 128

Control Table (partial)

Dialog | Control | Attributes
Dialog1 | Edit1 | 2097152
Dialog1 | Edit2 | 1048576

Because the Password Control Attribute (2097152) is not used with Windows Installer version 1.0, but is used with version 1.1, the warning on this bit in Edit1 appears when the Page Count Summary Property is 100

See Also

ICE Reference


ICE46

ICE46 checks for custom properties in conditions, formatted text, and other locations that differ from a system defined property only by the case of one or more characters.

Result

ICE46 posts an informational message if there is a custom property in a condition, formatted text, and other location that differs from a system defined properties only in the case of one or more characters.

Example

ICE46 reports the following errors for the example shown.

ICE46 error | Description
Property ReinstallMode defined in property table differs from another defined property only by case. | The system defined property name REINSTALLMODE differs from the custom property by case only. Properties are case sensitive, so custom property is not the same as the system property. This is a common cause of errors.
Property 'Myproperty' referenced in column 'InstallExecuteSequence'.'Condition' of row 'InstallFinalize' differs from a defined property by case only. | The property table defines the table MyProperty, but the referenced property is Myproperty. Properties are case sensitive, so the two properties are NOT the same. This is a common cause of errors.

Property Table

Property | Value
ReinstallMode | omus
MyProperty | a value

InstallExecuteSequence Table (partial)

Action | Condition
InstallFinalize | Myproperty

See Also

ICE Reference


ICE47

ICE47 checks the Feature and FeatureComponents tables for features with 1600 or more components.

Result

ICE47 posts an error message if a feature exceeds the maximum limit of 1600 components per feature on Windows NT/Windows 2000 and 800 components per feature on Windows 95 and Windows 98.

Example

ICE47 would report the following warning:

Feature 'Feature1' has 1600 components. This could cause
    problems on Win9X systems. You should try to have less
    than 800 components per feature."

Feature Table (partial)

Feature
Feature1

FeatureComponents Table (partial)

Action | Condition
Feature1 | Component1
Feature1 | Component1600

To fix this warning, try splitting the feature into several features

See Also

ICE Reference


ICE48

ICE48 checks for directories that are hard-coded to local paths in the Property table.

Do not hard-code directory paths to local drives because machines differ in the setup of the local drive. This practice may be acceptable if deploying an application to a large number of computers on which the relevant portions of the drives are all the same.

Result

ICE48 posts an error message if there is a directory that is hard-coded to a local path in the Property table.

Example

ICE48 would report the following warning for the example shown.

Directory 'Dir1' appears to be hardcoded in the property
    table to a local drive.

Directory Table (partial)

Directory | Directory_Parent | DefaultDir
Dir1 |  | SourceDir

Property Table (partial)

Property | Value
Dir1 | d:\source

See Also

ICE Reference


ICE49

ICE49 checks for default registry entries that are not a REG_SZ type.

Result

ICE49 posts an error if there is a default registry entry that is not a REG_SZ type.

Example

ICE49 reports the following warning for the example shown.

Reg Entry 'Reg1' is not of type REG_SZ. Default types must be REG_SZ
    on Win95 Systems. Make sure the component is conditionalized
    to never be installed on Win95 machines.

The value '#123' is a DWORD registry value. On Microsoft® Windows® 95 computers, default registry entries (those with no name) can only be REG_SZ values. On Microsoft® Windows® 98 and Microsoft® Windows® NT/Windows® 2000 systems, default values can be of any type. Components with non-REG_SZ default values are valid, as long as they are never installed on a Win95 machine. If they are, an error is generated at install time.

Registry Table (partial)

Registry | Name | Value
Reg1 |  | #123

To fix this error, make installation of the component conditional upon the target not being a Windows 95 machine, or change the value to type REG_SZ.

You can use the following properties to author a conditional statement VersionNT, Version9X, and WindowsBuild. For example, a possible condition is: "VersionNT OR (Version9x AND WindowsBuild>=1998).

See Also

Conditional Statement Syntax, ICE Reference


ICE50

ICE50 checks that shortcut icons are specified to display correctly and match their target file's extension.

Result

ICE50 posts an error message if the extension of the icon and target files do not match. ICE50 posts a warning if icons are stored in files that do not have an .exe or .ico extension.

Example

ICE50 reports the following error for the example shown.

ICE50 error or warning | Description
The extension of Icon 'Icon2.dat' for Shortcut 'Shortcut2' does not match the extension of the Key File for component 'Component2'. | If the extensions of the icon and the target file do not match, the shortcut will not have the correct context menu when the component is advertised. To fix this error, rename the icon to match the extension of the target file.
The extension of Icon 'Icon1.bat' for Shortcut 'Shortcut1' is not "exe" or "ico". The Icon will not be displayed correctly. | Not all versions of the shell correctly display icons stored in files that do not have extensions of "exe" or "ico". To fix this warning, rename the icon have an extension of "exe" or "ico".

File Table (partial)

File | FileName
File1 | File1.bat
File2 | File2.pl

Feature Table (partial)

Feature
Feature1

Component Table (partial)

Component | KeyPath
Component1 | File1
Component2 | File2

Icon Table

Name | Data
Icon1.bat | [Binary Data]
Icon2.dat | [Binary Data]

Shortcut Table (partial)

Shortcut | Component | Target | Icon_
Shortcut1 | Component1 | Feature1 | Icon1.bat
Shortcut2 | Component2 | Feature1 | Icon2.dat

See Also

ICE Reference


ICE51

ICE51 checks for TTC/TTF fonts that have titles and other fonts that are missing titles.

You must specify a title for fonts that do not have embedded names.

TTF/TTC fonts have the title of the font embedded in the file itself. Do not specify a title for these fonts because the font is then registered twice, once under the supplied name and again under the embedded name.

Result

ICE51 posts an error or warning if there are any TTC/TTF fonts with titles or other fonts missing titles.

Example

ICE51 would report the following warning for the example shown.

Font 'Font1' is a TTC\TTF font, but also has a title.

ICE51 would report the following error message for the example shown.

Font 'Font2' does not have a title. Only TTC\\TTF fonts do not need titles.

File Table (partial)

File | FileName
Font1 | font1.ttf
Font2 | font2.fon

Font Table

File_ | FontTitle
Font1 | A Really Cool Font
Font2 |

See Also

ICE Reference


ICE52

ICE52 checks for private properties in the AppSearch table. See About Properties.

When using Windows 2000 all properties set in the Property column of the AppSearch table must be public properties.

Result

ICE52 posts a warning if there is a private property in the AppSearch table.

Example

ICE52 posts the following warning for the example shown.

Property 'Property2' in AppSearch row 'Property2'.'Signature2'
    is not public. It should be all uppercase.

AppSearch Table

Property | Signature
PROPERTY1 | Signature1
Property2 | Signature2

To fix this warning change to the custom public property: PROPERTY2.

See Also

ICE Reference


ICE53

ICE53 checks for entries in the Registry table that write private installer information or policy values to the system registry.

Result

ICE53 posts a warning if the Registry table specifies writing internal or policy information to the registry.

Example

ICE53 posts the following warning for the example shown.

Registry Key 'Registry1' writes Installer internal or policy information.

Registry Table (partial)

Registry | Root | Key
Registry1 | 1 | Software\Policies\Microsoft\Windows\Installer\DisableRollback

Registry table row 'Registry1' writes a system policy value in the registry that affects the installation of all packages. Depending on the package, it may be possible to disable rollback for this package alone by setting the DISABLEROLLBACK property in the Property table. See Rollback Installation.

See Also

ICE Reference


ICE54

ICE54 checks for components that use a companion file as their key path.

The key path file of a component must not derive its version from a different file. This can cause some files to fail to install. See the File table for more information about companion files.

Result

ICE54 posts a warning if any component has a key path file that derives its version from another file.

Example

ICE54 returns the following warning for the example shown.

Component 'Component1' uses file 'File1' as its KeyPath, but the file's version is provided by the file 'File2'.

Component Table (partial)

Component | Attribute | KeyPath
Component1 | 0 | File1

File Table (partial)

File | Version | Language
File1 | File2 |
File2 | 1.0.0.0 | 1033

See Also

ICE Reference


ICE55

ICE55 validates that all LockPermission objects exist and have valid permission values.

Result

ICE55 post an error if a LockObject listed in the LockPermissions table does not exist or if no privilege level is specified in the Permission column.

Example

ICE55 would report the following errors for the example.

LockObject 'File1'.'File'.''.'guest' in the LockPermissions table
    has a null Permission value.
Could not find item 'File3' in table 'File' which is referenced
    in the LockPermissions table.

LockPermissions Table (partial)

LockObject | Table | Domain | User | Permission
File1 | File |  | guest |
File3 | File |  | guest | 1

File Table (partial)

File | Version | Language
File1 | File2 |
File2 | 1.0.0.0 | 1033

The object File1 has a null in the Permission column. Each row must have a value in the Permissions column. To fix this error specify a numeric value in this column. If no privileges are needed for this object then you should remove the row.

The object File3 described in the LockPermissions table is not listed in the File table. To fix this error refer to a valid object.

See Also

ICE Reference


ICE56

ICE56 validates that the directory structure of the .msi file has a single root directory, that the root is the TARGETDIR property, and that the SourceDir property value is in the DefaultDir column of the Directory table.

If a .msi file has multiple roots or specifies a root other than TARGETDIR, an administrative installation does not create a correct administrative image.

Result

ICE56 posts an error if the .msi does not have a single root, TARGETDIR, or if SourceDir is not specified in the DefaultDir column of the Directory table.

Example

ICE56 reports the following errors for the example shown.

Directory 'TARGETDIR' has a bad DefaultDir value.
Directory 'Root2' is an invalid root Directory.

Directory Table

Directory | Directory_Parent | DefaultDir
TARGETDIR |  | Temp
Root2 | Root2 | SourceDir

To fix the first error, the TARGETDIR root should have a DefaultDir value of SourceDir. SOURCEDIR is also accepted. It may be possible to make TARGETDIR the parent of the second root, and use the '.' value in the DefaultDir column. See the Directory table for more information.

To fix the second error, the Directory structure should have only one root called TARGETDIR.

See Also

ICE Reference


ICE57

ICE57 validates that individual components do not mix per-machine and per-user data. This ICE custom action checks registry entries, files, directory key paths, and non-advertised shortcuts.

Mixing per-user and per-machine data in the same component could result in only partial installation of the component for some users in a multi-user environment.

See the ALLUSERS property.

Result

ICE57 posts an error if it finds any component that contains both a per-machine and per-user registry entries, files, directory key paths, or non-advertised shortcuts.

Example

ICE57 reports the following errors for the example shown.

Component 'Component1' has both per-user and per-machine
    data with a per-machine KeyPath.

WARNING: Component 'Component2' has both per-user and
    per-machine data with an HKCU Registry KeyPath.

Component 'Component3' has a registry entry that
    can be either per-user or per-machine and a per-machine KeyPath.

Component 'Component4' has both per-user data and
    a keypath that can be either per-user or per-machine.

Component Table (partial)

Component | Directory | Attributes | KeyPath
Component1 | DirectoryA | 0 | FileA
Component2 | DirectoryA | 4 | RegKeyB
Component3 | DirectoryA | 0 | FileC
Component4 | DirectoryA | 4 | RegKeyD

Registry Table (partial)

Registry | Root | Component_
RegKeyA | 1 | Component1
RegKeyB | 1 | Component2
RegKeyC | -1 | Component3
RegKeyD | -1 | Component4

File Table (partial)

File | Component_
FileA | Component1
FileB | Component2
FileC | Component3
FileD | Component4

Directory Table

Directory | Directory_Parent | DefaultDir
TARGETDIR |  | SourceDir
DirectoryA | TARGETDIR | DirectoryA

To fix the errors, reorganize the application such that each component contains only per-user or per-machine resources, and not both.

The first error message is posted because Component1 contains FileA (per-machine) and the HKCU registry key RegKeyA (per user).

See Also

ICE Reference


ICE58

ICE58 checks that your Media table does not have more than 80 rows.

Result

Errors reported by ICE58 cause the installation to fail.

Example

ICE58 reports the following errors and warnings for the example shown.

This package has 81 media entries. Packages are limited to 80 entries in the media table.

To fix this error, eliminate any unused media table entries, consolidate media table entries that refer to the same media, and repackage your application to reduce the media required.

Media Table (partial)

DiskId | LastSequence_
1 | 10
2 | 20
... | ...
81 | 810

See Also

ICE Reference


ICE59

ICE59 checks that advertised shortcuts belong to components that are installed by the target feature of the shortcut.

Errors reported by ICE59 generally lead to the following behavior:

  1. The advertised shortcut will launch the Windows Installer to install the feature listed in the Target column.
  2. But because the FeatureComponents table does not map the target feature to the component containing the shortcut, the keyfile of the component (which is activated by the shortcut) is not installed.
  3. Therefore the shortcut is broken and will not do anything.

Result

ICE59 posts an error if an advertised shortcut does not belong to the components that are installed by the target feature of the shortcut.

Example

ICE59 reports the following error for the example shown:

The shortcut ShortcutB activates component ComponentB and advertises feature FeatureA, but there is no mapping between FeatureA and ComponentB in the FeatureComponents table.

In this case, ShortcutB advertises FeatureA, and when activated, starts the key file of ComponentB. Yet ComponentB is never installed by FeatureA, so even after the installation-on-demand phase completes, the target of the shortcut does not exist.

To fix this error, add a row to the FeatureComponents table that associates FeatureA and ComponentB.

Shortcut Table (partial)

Shortcut | Target | Component_
ShortcutB | FeatureA | ComponentB

FeatureComponents Table

Feature_ | Component_
FeatureA | ComponentA

Feature Table (partial)

Feature | Level
FeatureA | 10

Component Table (partial)

Component | KeyPath
ComponentA | FileA
ComponentB | FileB

File Table (partial)

File | Component_ | Sequence
FileA | ComponentA | 1
FileB | ComponentB | 2

See Also

ICE Reference


ICE60

ICE60 checks that files in the File table meet the following condition:

  • If the file is not a font and has a version, then it must have a language.

Failure to fix a warning reported by ICE60 generally leads to a file being needlessly reinstalled when a product repair is done. This happens because the file to be installed in the repair and the existing file on disk have the same version (they are the same file) but different languages. The file table lists the language as null, but the file itself has a language value in the resource. Based on the file versioning rules, the installer favors the file to be installed, so it is recopied needlessly.

Result

ICE60 posts a warning or an error if a file in the File table that is not a font and has a version, does not have a language.

Example

ICE60 reports the following error and warning for the example shown. (File B is a font; the other files are not.)

WARNING: The file FileE is not a Font, and its version is not a companion file reference. It should have a language specified in the Language column.

FileA has both a version and a language; therefore no warning or error is generated.

FileB has a version but no language. No warning or error is generated, however, because it is a font.

FileC is a companion reference, so it does not have to have a language. No warning or error is generated.

FileD has no version, so it does not need to have a language. No warning or error is generated.

FileE has a version but no language. Therefore a warning is generated.

To fix this warning, add a language to FileE.

Files should have language values stored in the version resource whenever possible. If a file is language neutral, use the LANGID 0.

File Table (FileB is a font; the other files are not.)

File | Version | Language
FileA | 1.0 | 1033
FileB | 1.0 |
FileC | FileA |
FileD |  |
FileE | 1.0 |

Font Table

File | FontTitle
FileB | Font Title

See Also

ICE Reference


ICE61

ICE61 checks the upgrade table to ensure that the following conditions are true:

  • All ActionProperty properties are not pre-authored in the Property table.
  • All ActionProperty properties are Public Properties.
  • All ActionProperty properties are included in the SecureCustomProperties property.
  • All ActionProperty properties are unique to each record in the Upgrade table.
  • All VersionMax values are not less than the corresponding VersionMin values.
  • No attempt is made to remove a newer or equal version of the current product.

Failure to fix a warning or error reported by ICE61 generally leads to problems in upgrading your application. Depending on the exact error, this could be anything from leaving files from the older version behind, deleting files from the older version even though they are needed by the new application, or complete failure of the upgrade.

Result

ICE61 posts a warning or error if any of the above conditions are not true.

Example

ICE61 reports the following errors and warning for the examples shown.

This product should remove only older versions of itself. The Maximum version is not less than the current product. (2.01.0000 2.01.0000)

In this case, the first row would try to remove a product of the same version. (VersionMax column is equal to the product version in the Property table).

To fix this error, use a version in the VersionMax column lower than the current version specified in the Property table. Remove the msidbUpgradeAttributesVersionMaxInclusive bit from the Attributes column if the VersionMax is equal to the current version. If the intent is only to detect the product and not remove it, adding the msidbUpgradeAttributesOnlyDetect bit to the Attributes column will also fix this error.

Upgrade.ActionProperty EnglishAPPFOUND must be added to the SecureCustomProperties property.

Unless the property is listed in the SecureCustomProperties property, the property is not passed to the server side of the install when the property is found.

To fix this error, add the property to SecureCustomProperties

Upgrade.ActionProperty EnglishAPPFOUND must not contain lowercase letters.

Upgrade properties must be public properties for the result to be passed to the server side of the installation.

To fix this error, use all uppercase letters in the property name.

Upgrade.ActionProperty OLDAPPFOUND may be used in only one record of the Upgrade table.

A property can only be used in one row of the Upgrade table.

To fix this error, use a different property for the second row.

Upgrade.VersionMax cannot be less than Upgrade.VersionMin. (OLDAPPFOUND)

The minimum version must be less than the maximum version.

To fix this error, check your version numbers for typos. If they are correct and you want to use the range between the two versions, switch them so that VersionMin is less than VersionMax.

Property Table

Property | Value
UpgradeCode | {61AA4C55-E17F-11D2-93BB-0060089A76DB}
ProductVersion | 2.01.0000
SecureCustomProperties | OLDAPPFOUND

Upgrade Table

UpgradeCode | VersionMin | VersionMax | Language | Attributes | Remove | ActionProperty
{61AA4C55-E17F-11D2-93BB-0060089A76DB} |  | 2.01.0000 |  | 513 |  | OLDAPPFOUND
{61AA4C55-E17F-11D2-93BB-0060089A76DB} | 2.01.0001 | 2.01.0000 |  |  |  | OLDAPPFOUND
{C6CB4596-D8E8-D5A4-635F-9FE456D682EB} | 1.00.0000 | 2.00.0000 | 1033 |  | [AppFeatureEnglish] | EnglishAPPFOUND

See Also

ICE Reference


ICE62

ICE62 performs extensive checks on the IsolatedComponent table for data that may cause unexpected behavior.

Failure to fix an error reported by ICE62 can result in a failure of the isolated component system in a wide variety of ways. For example, if the SharedDllRefCount bit is not set for a shared component, the registration for the component could be removed when another application uses that ComponentId and is uninstalled.

Result

ICE62 posts a warning or error when it finds data in the IsolatedComponent table that may produce unexpected behavior.

Example

ICE62 reports the following errors and warning for the examples shown.

The component 'Component2' is listed as an isolated application
component in the IsolatedComponent table, but the key path is not a file.

Component2 is listed as the application component for the isolation of component1. However, Component2 has a registry key path, and does not provide a valid executable path to use to isolate the component.

To fix this error, use a different component as the application for the isolated component Component1.

The component 'Component1' is listed as an isolated shared component in the
IsolatedComponent table, but is not marked with the SharedDllRefCount component attribute.

Component1 is listed as an isolated shared component, but does not have the SharedDllRefCount bit set. This could result in the lifetime of the component being incorrect. If another application uses this component (isolated or not) and is uninstalled, the registration for the component is removed but this application's isolated copy remains. This causes repair and uninstall problems.

To fix this error, set the SharedDllRefCount bit for the component.

The isolated shared component 'Component1' is not installed by the same feature as
(or a parent feature of) its isolated application component 'Component2' (which is installed by feature 'Feature2').

Component1 and Component2 are installed by different features. Component1 is installed by Feature1, and Component2 is installed by Feature2. Feature1 is not a parent of Feature2, hence it is possible for the application to be installed but not the isolated component, breaking the isolation.

To fix this error, add an entry to the FeatureComponents table linking Component1 to the same feature as (or a parent feature of) the feature that installs Component2.

WARNING: The isolated shared component 'Component1' (referenced in the IsolatedComponent table)
is conditionalized. Isolated shared component conditions should never change from TRUE to FALSE after the first install of the product.

Component1 has a condition in the Component table. If this condition ever changes from TRUE to FALSE during the lifetime of an installation on a computer, the isolated component could be orphaned without registration information.

To fix this warning, remove the condition, or author the condition so that it can never change from TRUE to FALSE.

WARNING: The isolated shared component 'Component1' is shared by multiple applications
(including 'Component2') that are installed to the directory 'TARGETDIR'.
WARNING: The isolated shared component 'Component1' is shared by multiple applications
(including 'Component3') that are installed to the directory 'TARGETDIR'.

Component1 is isolated for both Component2 and Component3, and the two components are also installed to the same directory. The applications share an isolated component, but if one application is removed the shared component is removed as well causing the other applications to lose the isolated component.

To fix this warning, install the applications to different directories or check whether some of the applications truly require an isolated component.

IsolatedComponent Table

Component_Shared | Component_Application
Component1 | Component2
Component1 | Component3

Component Table

Component | ComponentId | Directory_ | Attributes | Conditiion | KeyPath
Component1 |  | Dir1 | 0 | MYCONDITION | File1
Component2 |  | TARGETDIR | 4 |  | Registry2
Component3 |  | TARGETDIR | 0 |  | File3

FeatureComponents Table

Feature_ | Component_
Feature1 | Component1
Feature2 | Component2
Feature1 | Component3

Feature Table (partial)

Feature | Feature_Parent
Feature1 |
Feature2 |

See Also

ICE Reference


ICE63

ICE63 checks for proper sequencing of the RemoveExistingProducts action. The RemoveExistingProducts action may be placed:

  1. Between InstallValidate and InstallInitialize
  2. Immediately after InstallInitialize, or after InstallInitialize if the actions between InstallInitialize and RemoveExistingProducts do not generate any script actions.
  3. Immediately after InstallExecute or InstallExecuteAgain and before InstallFinalize (the same restriction as above applies).
  4. After InstallFinalize.

Failure to fix a warning or error reported by ICE63 leads to failure of the upgrade.

Result

ICE63 posts a warning or error if the sequencing of the RemoveExistingProducts action is not correct.

Example

ICE63 reports the following error for the example shown.

WARNING: Some action falls between InstallInitialize and RemoveExistingProducts.

The action 'MyCustomAction' occurs between InstallInitialize and RemoveExistingProducts. If MyCustomAction generates any actions in the script, this causes problems in the installation.

To fix this error, verify that MyCustomAction does not generate any script actions or resequence the actions.

InstallExecuteSequence Table

Action | Condition | Sequence
InstallInitialize |  | 1000
MyCustomAction |  | 1010
RemoveExistingProducts |  | 1020

See Also

ICE Reference


ICE64

ICE64 checks that new directories in the user profile are removed correctly in roaming scenarios.

Failure to fix a warning or error reported by ICE64 generally leads to problems in completely cleaning the machine during an uninstallation. When a roaming user who has installed the application logs on to a computer for the first time, all of the profile is copied down onto the computer. On advertisement (which takes place after the roaming profile download), the Installer verifies that the directory is already there and therefore does not delete it on uninstallation. This leaves the directory on the user's computer permanently.

Result

ICE64 posts a warning or an error in a roaming situation if a new directory in the user profile that should be removed is not removed.

Example

ICE64 reports the following error for the example shown.

The directory 'MyOtherFolder' is in the user profile but is not listed in the RemoveFile table.

The folder 'MyOtherFolder' is a custom profile folder. Because it is not listed in the RemoveFile table, it is not removed in some scenarios.

To fix this error, create a row for the folder in the RemoveFile table.

Directory Table

Directory | Directory_Parent | DefaultDir
AppDataFolder | TARGETDIR |
MyFolder | AppDataFolder | DataFolder
MyOtherFolder | AppDataFolder | DataFolder2

RemoveFile Table

FileKey | Component_ | FileName | DirProperty | InstallMode
Key1 | Component1 |  | MyFolder | 2

See Also

ICE Reference


ICE65

ICE65 checks that the Environment table does not have invalid prefix or append values.

Failure to fix a warning or error reported by ICE65 generally leads to problems in install, uninstall, or repair of the environment variable. For example, only some values of a particular variable may be removed if one or more of the values for that variable have a trailing separator.

Result

ICE65 posts a warning or an error if the environment table has invalid prefix or append values.

Example

ICE65 reports the following error and warning for the example shown.

The environment variable 'Var3' has a separator beginning or ending its value.

The trailing null at the end of the value ([~]) marks this value to be prepended to any existing value. The character immediately before the NULL (a semicolon) becomes the separator for this value. This value has a semicolon at the beginning of the string as well.

To fix this error, simply delete the leading semicolon.

WARNING: The environment variable 'Var2' has an alphanumeric separator

The leading null in the value ([~]) marks this value to be appended to any existing value. The character immediately after the NULL becomes the separator for this value. In this case, that character is the letter "e", which also occurs in the middle of the string to be appended. This condition (having a separator that is the same as a character within the string to be appended) can cause unpredictable results.

The letter "e", being a common letter, is likely to be found in the value. A better choice would be ";" or some other non-alphanumeric character. (However, if the value is a path, then ":" and "\" and "." are risky choices.)

To fix this warning, use a different separator character.

Environment Table

Component | Directory | Attributes | KeyPath
Var1 | TestVar | [~];AppendThis | TestComponent
Var2 | TestVar | [~]eAppendThis | TestComponent
Var3 | TestVar | ;PrependThis;[~] | TestComponent

See Also

ICE Reference


ICE66

ICE66 uses the tables in the database to determine which schema your database should use.

Some functionality may only be available if the package is installed on a system with Windows Installer version 1.1 or later.

Result

ICE66 posts a warning if your database is using the wrong schema.

Example

ICE66 reports the following warning for the example shown.

WARNING: Complete functionality of the IsolatedComponents table is only available with Windows Installer versions 1.1 or greater. Your schema is 100.

The IsolatedComponent Table was added in version 1.1 of the installer. In order for you to have the additional functionality resulting from use of the IsolatedComponent table, the package must be installed on a system with Windows Installer version 1.1 or greater.

This warning can be ignored if you want your package to work on Windows Installer version 1.0 and have the additional functionality of the IsolatedComponents table if your package is installed on Windows Installer version 1.1 or greater. If you are not using the IsolatedComponents table, drop it from your database. If you want your package to be installable only on version 1.1 or later, change your package schema (PID_PAGECOUNT) to 110.

IsolatedComponent Table

Component_Shared | Component_Application
Component1 | Component2

Summary Information Stream

PIDt | Value
PID_PAGECOUNT | 100

Table used during execution:

_Columns table

See Also

ICE Reference


ICE67

ICE67 checks that the target of a non-advertised shortcut belongs to the same component as the shortcut itself, or that the attributes of the target component ensure that it does not change installation locations.

Failure to fix a warning or error reported by ICE67 can cause the shortcut to be invalid if the target component changes state and the source component does not. For example, when the target file's component is set to run from source, a reinstallation that changes the component to local results in the component containing the shortcut not being reinstalled. Thus the shortcut points to an invalid location.

Note that in some cases, using a different component for the shortcut is unavoidable. For example, if the shortcut is created in the user profile and the file is installed to a non-profile directory, you may not be able to use the same component for both pieces of data. (This results in failures in multi-user scenarios – such as those described in ICE57). In this case, you may be able to use advertised shortcuts to achieve the behavior you want, or you can simply ensure that the target component cannot change from run-from-source to local.

Result

ICE67 returns an error or a warning if the target of a non-advertised shortcut does not belong to the same component as the shortcut itself, or if the attributes of the target component do not ensure that the installation locations will not change.

Example

ICE67 reports the following warning and errors for the example shown.

The shortcut 'Shortcut1' is a non-advertised shortcut with a file target. The shortcut and target are installed by different components, and the target component can run locally or from source.

Shortcut1 is installed by Component2, but its target file, File1, is installed by component1. The target component is marked optional (meaning that it can be local or run-from-source). One possible situation that would cause a problem is if Component1 changes from run-from-source to local. This would cause Shortcut1 to point to an invalid location.

To fix this warning, Install the shortcut as part of Component1, or mark Component1 as LocalOnly or SourceOnly.

File Table (partial)

File | Component_
File1 | Component1

Shortcut Table (partial)

Shortcut | Component_ | Target
Shortcut1 | Component2 | [#File1]

Component Table (partial)

Component | Attributes
Component1 | 2

See Also

ICE Reference


ICE68

ICE68 checks that all custom action types needed for an installation are valid. Failure to fix a warning or error reported by ICE68 causes an installation that attempts to execute the action to fail.

Result

ICE68 returns an error if an action type needed for an installation is invalid.

Example

ICE68 reports the following error for the example shown:

Invalid custom action type for action 'Action1'.

1027 is not a valid action type.

To fix this error, choose a valid custom action type.

CustomAction Table (partial)

Action | Type | Source | Target
Action1 | 1027 | Argument | Component1

See Also

ICE Reference


ICE69

ICE69 checks that all substrings of the form [$componentkey] within a Formatted string do not cross-reference components. A cross-component reference occurs when the [$componentkey] property of a formatted string refers to a component other than the component stored in the Component_ column of your tables.

Problems with cross-component referencing of components arise from the way formatted strings are evaluated. If the component referenced with the [$componentkey] property is already installed and is not being changed during the current installation (for example, being re-installed, moved to source, etc.), the expression [$componentkey] evaluates to null, because the action state of the component in [$componentkey] is null. Similar problems can occur during upgrade and repair operations.

Result

ICE69 returns an error if a [$componentkey] substring within a Formatted string cross-references a component in another feature. ICE69 returns a warning if a [$componentkey] substring within a Formatted string cross-references a component in the same feature. (The FeatureComponents table is used to determine this mapping. It must map to the same feature for the warning. Referencing components in parent features or referencing components in child features is considered to be an error.)

Example

ICE69 reports the following for the examples shown.

WARNING: "Mismatched component reference. Entry 'Test' of the Shortcut table belongs to component 'QuickTest'. However, the formatted string in column 'Argument' references component 'Test'. Components are in the same feature."
ERROR: "Mismatched component reference. Entry 'Shortcut2' of the Shortcut table belongs to component 'QuickTest'. However, the formatted string in column 'Argument' references component 'Test2'. Components are not in the same feature."

To fix this error, do not cross-reference components. Change the [$componentkey] to match the component of the shortcut.

Shortcut Table (partial)

Shortcut | Component_ | Argument
Test | QuickTest | -v [$Test]
Shortcut2 | QuickTest | [$Test2]

The Verb and Extension tables are special cases in that the Verb table references an extension that belongs to a component. An Extension, however, can belong to multiple components because the primary key for the extension table is made up of the Extension and Component_ columns. You can logically have the following situation.

Verb Table (partial)

Extension | Verb_ | Argument
tst | open | -v [$comp1][$comp2]

Extension Table (partial)

Extension | Component_
tst | comp1
tst | comp2

FeatureComponents Table

Feature_ | Component_
Feature1 | QuickTest
Feature1 | Test
Feature2 | Test2

In this case, you must ensure that at least one of the [$componentkey] properties evaluates to a non-null value. However, every [$componentkey] property in the Argument column of the Verb table ([$comp1] and [$comp2] in the above example) must reference a possible component included with the extension associated with the verb. A reference like [$comp3] would result in a warning from ICE69.

The AppId table has a similar situation to the Verb table. It uses the Class table for its component reference. In this case, the AppId table is validated in the same way as the Verb-Extension validation (now AppId-Class).

The Class table's Argument column is validated like the Shortcut, Registry, and similar tables.

Table used during execution (only if found)

IniFile

RemoveIniFile

Registry

RemoveRegistry

ServiceControl

ServiceInstall

Shortcut

Verb

Extension

Class

AppId

Environment

See Also

ICE Reference


ICE70

ICE70 verifies that integer values for registry entries are specified correctly. Values of the form ##str, #%unexpanded str are not validated. Values of the form #xhex, #Xhex, #integer, and #[property] are validated. The following table provides a brief overview.

Value | Validation
##str | valid
#%unexpanded str | valid
#xHex,#XHex | Validate for valid hex characters (0-9,a-f,A-F). Properties are allowed here.
#+int, #-int, #int | Validate for valid numeric characters (0-9). Properties are allowed here.

The syntax for an integer value to be entered into the registry is #integer where integer is numerical.

Result

ICE70 reports an error if integer values for registry entries are not specified correctly.

Example

ICE70 reports the following errors for the given example.

The value #12xz34 is an invalid numeric value for registry entry Reg1. If you meant to use a string, then the string value entry must be preceded by ## not #.

To fix this error: If you want the value to be numeric, change the value to use all numeric characters. If you want the value to be a string, it must be preceded by two '#' (##) instead of just one.

The value #xz34 is an invalid hexadecimal value for registry entry Reg2.

To fix this error: Valid hexadecimal characters are 0-9, A-F, and a-f. Only these characters can follow the #x (or #X).

Registry table (partial)

Registry | Value
Reg1 | #12xz34
Reg2 | #xz34

Remarks

  • #[myproperty] is valid.
  • #[myproperty is not valid (missing ending bracket).
  • #[myprop1] [myprop2 is valid. (Even though the last one is missing the ending bracket, myprop1 could evaluate to #str so you would have ##str [myprop2, which is valid
  • #]myproperty[ is not valid
  • Any embedded property in a value string cannot be in [$compkey], [#filekey], or [!filekey] form because these are not numeric. However, there is one exception, #[myproperty] [$compkey] (or [#filekey] or [!filekey]) is valid because, as with the preceding, [myproperty] can evaluate to #str.

See Also

ICE Reference


ICE71

ICE71 verifies that the Media table contains an entry with DiskId equal to 1. (Windows Installer assumes that the .msi package is on disk 1.)

Result

ICE71 returns an error if the Media table does not contain an entry with DiskId equal to 1.

Example

ICE71 reports the following error for the example shown.

The Media table requires an entry with DiskId=1. First DiskId is '2'.

T0 fix this error, change the DiskId of the entry where the package is stored to 1.

Media Table (partial)

DiskId
2

See Also

ICE Reference


ICE72

ICE72 verifies that non-built-in custom actions are not used in the AdvtExecuteSequence table. Specifically, only type 19, type 35, and type 51 custom actions are allowed in the AdvtExecuteSequence table. If other custom actions are used, advertisement may not behave as expected.

Result

ICE72 returns an error if the AdvExecuteSequence table uses custom actions other than type 35, type 51, and type 19.

Example

ICE72 reports the following error for the example shown:

Custom Action 'CA1' in the AdvtExecuteSequence table is not allowed. Only built-in custom actions are allowed.

To fix the error, remove 'CA1' from the AdvtExecuteSequence table.

AdvtExecuteSequence Table (partial)

Action
CA1
CA35

CustomAction Table (partial)

Action | Type
CA1 | 1
CA35 | 35

Tables used during execution

AdvtExecuteSequence Table

CustomAction Table

See Also

Custom Action Type 19, Custom Action Type 35, Custom Action Type 51, ICE Reference


ICE73

ICE73 verifies that your package does not reuse package codes, upgrade codes, or product codes of the Windows Installer SDK samples. Packages should never reuse the package, upgrade, or product codes of another product.

Result

ICE73 outputs a warning if your product's package reuses a package or product code of a Windows Installer SDK sample.

Example

ICE73 reports the following errors for the example shown:

This package reuses the '{80F7E030-A751-11D2-A7D4-006097C99860}' ProductCode of the orca.msi 1.0 Windows Installer SDK package.
This package reuses the '{000C1101-0000-0000-C000-000000000047}' Package Code of the msispy.msi 1.0 Windows Installer SDK package.
This package reuses the '{8FC7****-88A0-4b41-82B8-8905D4AA904C}' Upgrade Code of a 1.1 Windows Installer SDK package.

Note The asterisks (****) in the GUID represent the range of GUIDs reserved for subsequent Windows Installer SDK packages.

To fix the errors, generate a new unique GUID for your package's product and package codes. You will also need a new unique GUID for your package's upgrade code.

Summary Information Stream (partial)

Property | Value
PID_REVNUMBER | {000C1101-0000-0000-C000-000000000047}

Property Table (partial)

Property | Value
ProductCode | {80F7E030-A751-11D2-A7D4-006097C99860}
UpgradeCode | {8FC70000-88A0-4b41-82B8-8905D4AA904C}

See Also

Package Codes, Product Codes, Revision Number Summary Property, UpgradeCode Property, ProductCode Property, ICE Reference


ICE74

ICE74 verifies that the FASTOEM property has not been authored into the Property table.

The FASTOEM property enables OEMs to reduce the time required to install Windows Installer applications for the first time. It cannot be used after the first install. The FASTOEM property must not be authored in the Property table because this interferes with subsequent installations for the maintenance, removal, or repair of the application.

Result

ICE74 posts an error if the FASTOEM property has been set in the Property table.

Example

ICE74 reports the following error if the FASTOEM property is set:

The FASTOEM property cannot be authored in the Property table.

Property Table (partial)

Property | Value
FASTOEM | 1

To fix this error remove the FASTOEM property from the Property Table.

See Also

FASTOEM property, Property table, ICE Reference


ICE75

[This is preliminary documentation and subject to change.]

ICE75 verifies that all Custom Action Type 17 (DLL), Custom Action Type 18 (EXE), Custom Action type 21 (JScript), and Custom Action Type 22 (VBScript) custom actions are sequenced after the CostFinalize action. These types of custom action use an installed file as their source. ICE75 checks the InstallUISequence Table, InstallExecuteSequence Table, AdminUISequence Table, and AdminExecuteSequence Table. Note that the CostFinalize action is required in these sequence tables.

This ICE75 custom action is only available for Windows Installer version 1.5 or later.

Result

ICE75 posts an error if it finds a custom action using an installed file as a source file that is not sequenced after the CostFinalize action.

Example

ICE75 reports the following errors for the example shown:

CostFinalize is missing from 'AdminUISequence'. CA_FileExe is a custom
 action whose source is an installed file. It must be sequenced after
the CostFinalize action.

CA_FileDLL is a custom action whose source is an installed file.  It
must be sequenced after the CostFinalize action in the
AdminExecuteSequence table

CustomAction Table (partial)

Action | Type | Source
CA_FileExe | 18 | FileExe
CA_FileDLL | 17 | FileDLL

AdminUISequence Table (partial)

Action | Sequence
CA_FileExe | 1100

AdminExecuteSequence Table (partial)

Action | Sequence
CA_FileDLL | 800
CostFinalize | 1000

To fix the errors, sequence the custom actions after the CostFinalize action.

See Also

ICE Reference


ICE76

ICE76 verifies the use of the SFP (WFP) catalog within Windows Installer packages for Windows Me. This ICE also verifies that no files in the BindImage table reference SFP catalogs.

Windows File Protection requires an exact match between the file and the signature embedded in the catalog file. Files that reference a SFP catalog must not be listed in the BindImage table because the effect of the BindImage action on these files differs between computers. Files referenced by SFP catalogs must be in components that are permanent or installed locally.

Result

ICE76 posts an error for each file in the BindImage table that is also in the FileSFPCatalog table.

ICE76 outputs an error if a file in the FileSFPCatalog table belongs to a component with any of the following true:

  • msidbComponentAttributesPermanent is not set in the Attributes column of the Component table.
  • msidbComponentAttributesSourceOnly is set in the Attributes column of the Component table.
  • msidbAttributesOptional is set in the Attributes column of the Component table..

Example

ICE76 reports the following error for the example:

File 'File1' references a SFP catalog. Therefore it cannot be in the BindImage table.

FileSFPCatalog Table (partial)

File_ | SFPCatalog_
File1 | Catalog1.Cat

BindImage Table (partial)

File_
File1

To fix this do not enter any files that reference SFP catalogs into the BindImage table.

See Also

BindImage Table, Component Table, FileSFPCatalog Table, Windows File Protection On Windows Millennium Edition, ICE Reference


ICE77

[This is preliminary documentation and subject to change.]

ICE77 verifies that custom actions with the msidbCustomActionTypeInScript bit set are sequenced after the InstallInitialize action and before the InstallFinalize action. ICE77 checks the sequence in the InstallExecuteSequence table and AdminExecuteSequence table.

Result

ICE77 posts an error if an in-script custom action is sequenced before the InstallInitialize action or after the InstallFinalize action.

ICE77 posts an error if the InstallInitialize action or the InstallFinalize action is missing.

Example

ICE77 reports the following errors for the example:

InstallFinalize is missing from 'InstallExecuteSequence'.
CA_InScriptInstall is a in-script custom action. It must be sequenced
before the InstallFinalize action.

CA_InScriptAdmin is a in-script custom action.  It must be sequenced
in between the InstallInitialize action and the InstallFinalize action
in the AdminExecuteSequence Sequence table.

CustomAction Table (partial)

Action | Type
CA_InScriptInstall | 1025
CA_InScriptAdmin | 1026

InstallExecuteSequence Table (partial)

Action | Sequence
CA_InScriptInstall | 2000
InstallInitialize | 1500

AdminExecuteSequence Table (partial)

Action | Sequence
CA_InScriptAdmin | 1400
InstallInitialize | 1500
InstallFinalize | 6600

To fix the errors, sequence the in-script custom actions after the InstallInitialize action and before the InstallFinalize action. The InstallInitialize and InstallFinalize actions must be present in the InstallExecuteSequence table and the AdminExecuteSequence table.

See Also

ICE Reference


ICE78

[This is preliminary documentation and subject to change.]

ICE78 verifies that that the AdvtUISequence table either does not exist or is empty. This is required because no UI is allowed during advertising.

Result

ICE78 posts an error if the AdvtUISequence table exists and is not empty.

Example

ICE78 reports the following error for the example:

Action 'Action1' found in AdvtUISequence table. No UI is allowed
during advertising. Therefore AdvtUISequence table must be empty or
not present.

InstallExecuteSequence Table (partial)

Action | Condition | Sequence
Action1 | TRUE | 1

To fix the error, either remove "Action1" from the table, or remove the table.

See Also

ICE Reference


Merge Modules

Merge modules provide a standard method by which developers deliver shared Microsoft® Windows® Installer components and setup logic to their applications. Merge modules are used to deliver shared code, files, resources, Registry entries, and setup logic to applications as a single compound file. Developers authoring new merge modules, or using existing merge modules, should follow the standard outlined in this section.

A merge module is similar in structure to a simplified Windows Installer .msi file. However, a merge module cannot be installed alone, it must be merged into an installation package using a merge tool. Developers wanting to use merge modules must obtain one of the freely distributed merge tools, such as Mergemod.dll, or purchase a merge tool from an independent software vendor. Developers can create new merge modules by using many of the same software tools used to create a Windows Installer installation package, such as the database table editor Orca provided with the Windows Installer SDK.

When a merge module is merged into the .msi file of an application, all the information and resources required to install the components delivered by the merge module are incorporated into the application's .msi file. The merge module is then no longer required to install these components and the merge module does not need to be accessible to a user. Because all the information needed to install the components is delivered as a single file, the use of merge modules can eliminate many instances of version conflicts, missing Registry entries, and improperly installed files.

For more information about merge modules, see:

  • About Merge Modules
  • Using Merge Modules
  • Merge Module Reference


About Merge Modules

Merge modules are essentially simplified .msi files, which is the file name extension for a Microsoft® Windows® Installer installation package. A standard merge module has an .msm file name extension.

A merge module cannot be installed alone because its lacks some vital database tables that are present in an installation database. Merge modules also contain additional tables that are unique to themselves. To install the information delivered by a merge module with an application, the module must first be merged into the application's .msi file.

A merge module consists of the following parts:

  • A Merge Module Database containing the installation properties and setup logic being delivered by the merge module.
  • A Merge Module Summary Information Stream describing the module.
  • A MergeModule.CABinet cabinet file stored as a stream inside the merge module. This cabinet contains all the files required by the components delivered by the merge module.

Multiple language merge modules can deliver components to an installation package in multiple languages. In a multiple language merge module the database contains the installation properties and logic for more than one language and the MergeModule.CABinet cabinet includes all the files necessary to install components with all the languages supported by the module.


Merge Module Database

[This is preliminary documentation and subject to change.]

The database of a merge module contains all the installation properties and setup logic for the module. It is essentially a simplified installer database or .msi file. Standard merge module database files are indicated by a .msm extension. For a list of all database tables that can exist in merge modules, see Merge Module Database Tables. The following tables are required in the database of every .msm file:

Component
Directory
FeatureComponents
File
ModuleSignature
ModuleComponents

Note that the Component, Directory, FeatureComponents, and File tables are also present in all .msi files. A merge module database does not contain a Feature table and so the .msi file cannot be installed alone. To install a merge module, it must first be merged by using a merge tool into a .msi file.

The ModuleSignature Table is only present in .msi files that has been merged with at least one .msm file. If this table is present in a .msi file, it contains one record for each merge module that has been previously merged into the installation database.

Merge modules may contain optional MergeModule Sequence tables. These tables occur only in .msm files. When the .msm files are merged into an .msi file, these tables modify the action sequence tables of the .msi file.

Merge modules may contain custom tables. These tables are used by custom actions defined in the merge module.

Merge modules rarely require user interface tables. These tables need to be present only in rare cases where the merge module requires input from the user during installation. For more information, see Authoring User Interfaces in Merge Modules.


Merge Module Summary Information Stream

[This is preliminary documentation and subject to change.]

Every merge module is required to have a Summary Information Stream containing the following properties. These properties are basically the same as for an installation package, see the main topic for each property. For a list of all the summary information streams in merge modules see Merge Module Summary Information Stream Reference.

Summary information property | Meaning in merge modules
Template Summary Property | Lists numeric language identifiers for all languages supported by the module. The first language in the list is the default language of the module.
Revision Number Summary Property | The unique GUID for this merge module.
Page Count Summary Property | Minimum required installer version. Stored as an integer in the form: Major * 100 + minor.
Word Count Summary Property | Enter 0 for this property. Note that in a merge module, files are always inside an embedded cabinet file regardless of the value of this property.


MergeModule.CABinet

[This is preliminary documentation and subject to change.]

Every file delivered by the merge module must be stored inside of a cabinet file that is embedded as a stream in the merge module's structured storage. In a standard merge module, the name of this cabinet is always: MergeModule.CABinet. For more information, see Generating MergeModule.CABinet Cabinet Files.


Multiple Language Merge Modules

[This is preliminary documentation and subject to change.]

Multiple language modules can deliver components with several different languages as a single compound file. The design and functionality of multiple language merge modules is similar to single language modules. A multiple language merge module has more than one language listed in the Template Summary Property. The database of a multiple language merge module contains all the setup information for multiple languages. The MergeModule.CABinet cabinet inside a multiple language merge module contains all the files for all the supported languages.

When applying a multiple language .msm file to a .msi file, you must indicate the final language of the installation package after the merge. In the case of a single language merge module, the merge module's File table lists every file present in the MergeModule.CABinet cabinet. In the case of a multiple language merge module, MergeModule.CABinet contains all the files for every language supported by the module, but only the subset of files for the final language goes into the module's File table. The merge tool must ensure that the module provides the subset of information and files required for the requested final language.

Every merge module has a default language specified in the Language column of the ModuleSignature table. The default language of a merge module is also shown as the first, or only, language in the Template Summary Property. Depending on the requested final language and the module's default language, the merge tool may apply language transforms to a multiple language merge module so that it can be opened in the requested language, or an approximation of the requested language. The language transforms are embedded inside the merge module. Merge tools must apply language transforms in adherence to the following general rules:

  • If the default and final languages are the same, the module can be merged without using language transforms.
  • If the default language is 0 (a language neutral module), the module can be merged without using language transforms.
  • If the final language is not the default language, the merge tool must apply one of the language transforms embedded in the module to change the module to the final language, or to an approximation of the final language.

For example, no language transforms are required if the final language is 1033 (US English) and the default language of the module is 1033 (US English), 0 (language neutral), or 9 (generic English).

Language transforms are required if the final language is 1033 (US English) and the default language is 1031 (German). In this case, the merge tool may first search the multiple language module for an embedded language transform to 1033 (US English). If that fails it may then search for a transform to a language with a matching primary LANGID, even if the secondary LANGID does not match. For example, if the tool cannot find a transform to 1033 (US English), it searches for a transform to 9 (Generic English). If this fails the merge tool searches for a transform to 0 (language neutral). If all these searches for a suitable transform fail, the module fails to open.

For more information, see Authoring Multiple Language Merge Modules.


Configurable Merge Modules

[This is preliminary documentation and subject to change.]

Merge modules (.msm files) may be authored to contain attributes that are configurable by the consumer of the merge module. This enables the merge module to be configured at the time the installation package and module are merged and installed by the end user. Configurable merge modules require version 1.5 of Mergemod.dll but can run on any version of the Windows Installer.

The implementation of configurable merge modules consists of two parts. First, when creating the merge module (.msm file), the merge module author adds information to the module database that specifies which items can be modified and how these items can be configured by the module user. The author adds entries to the Merge Module Database Tables that are reserved for configurable information (ModuleConfiguration table and ModuleSubstitution table), updates the _Validation table, and adds entries for the configurable merge module tables to the ModuleIgnoreTable table. The additions to the ModuleIgnore table are required to make the module compatible with Mergemod.dll versions earlier than 1.5.

Second, when merging the module into an installation package (.msi file), the end user of the module uses a merge tool. The merge tool calls Mergemod.dll to expose the configuration information in the module to a client configuration tool. The configuration tool may interact with the end user but is not required to expose all possible configuration options. If the user declines to provide a selection for a configurable item, the module may provide a default value. After the user gives the configuration tool his selections, the merge tool calls Mergemod.dll to perform the merge.

Configurable merge modules are fully compatible with tools earlier than Mergemod.dll version 1.5. In these cases, the tool uses the default values in the module.

For more information, see Using Configurable Merge Modules.


Using Merge Modules

[This is preliminary documentation and subject to change.]

For more details about using Windows Installer merge modules, see the following:

  • Authoring Merge Modules
  • Authoring Multiple Language Merge Modules
  • Applying Merge Modules
  • Using Configurable Merge Modules


Authoring Merge Modules

[This is preliminary documentation and subject to change.]

The following procedure describes the general steps to authoring merge modules.

To create a new merge module

  1. Obtain a software tool you can use to edit the merge module database.
  2. Obtain a blank merge module database.
  3. Generate a GUID for the merge module. You need to use this GUID when authoring the primary keys of database tables in the merge module.
  4. Add a record to the Component table for each component delivered by the merge. A Component table is required in every merge module. Note that merge modules operate with components and not with features. In certain cases, however, a database table entry may need to reference a feature. For details, see Referencing Features in Merge Modules.
  5. Add a Directory table to the merge module that specifies the layout of directories the merge module adds to the target database. A Directory table is required in every merge module.
  6. Import a blank FeatureComponents table into the merge module database. This empty table provides a guideline for the merge tool in cases where the .msi file does not contain its own FeatureComponents table.
  7. Collect all the files delivered by this merge module and create the MergeModule.CABinet cabinet file. Add the cabinet to the merge module as a stream inside the .msm file.
  8. Add a record to the File table for every file stored in MergeModule.CABinet.
  9. Add the information necessary to identify the merge module in the ModuleSignature table. Every merge module requires a ModuleSignature table.
  10. List the components in the merge module in the ModuleComponents table. Every merge module requires a ModuleComponents table.
  11. Add merge module sequence tables to the .msm file only if the merge module needs to modify the sequence tables of the target installation database.
  12. Add a _Validation table to the merge module. A merge module requires a _Validation table to pass validation.
  13. Merge modules require a user interface in only rare cases. Including a UI with a merge module is not recommended. In cases where a user interface is required, the UI tables can be merged into the .msi file the same as other tables.
  14. Add registry information to the appropriate registry tables in the merge module database. Add registry information for type libraries, classes, extensions, and verbs into the TypeLib, Class, AppId, ProgId, Extension, Verb, or MIME tables. All other registry information can go into the Registry table. The use of the SelfReg table is not recommended.
  15. Add the summary information to the Merge Module Summary Information Stream.
  16. Run validation on all merge modules before attempting to install.

See Also

Obtaining Blank Merge Module Databases, Obtaining Merge Module Authoring Tools, Naming Primary Keys in Merge Module Databases, Authoring Merge Module Component Tables, Authoring Merge Module Directory Tables, Authoring Merge Module FeatureComponents Tables, Generating MergeModule.CABinet Cabinet Files, Authoring Merge Module File Tables, Authoring ModuleSignature Tables, Authoring ModuleComponents Tables, Authoring Merge Module Sequence Tables, Validating Merge Modules, Authoring User Interfaces in Merge Modules, Authoring Merge Module Registry Tables, Authoring Merge Module Summary Information Streams, Merge Module Summary Information Stream Reference, Validating Merge Modules


Obtaining Merge Module Authoring Tools

[This is preliminary documentation and subject to change.]

To generate a merge module, you need to obtain a software tool with which to edit a .msm file. Because a .msm file is basically a simplified .msi file, you may be able to use the same tools used to create an installation database. For example, the application Orca.exe provided with the Windows Installer SDK.

An alternative is to purchase one of the installer packaging tools to be available from independent software vendors. There are several third party tools under development that may be used for producing merge modules. If you choose to use a third party tool you should verify that it generates merge modules that are consistent with the standard described in this document. In particular, you should determine that the editing tools have not done any of the following to the merge module.

  • Added extraneous tables to the merge module that are not referenced in the ModuleIgnoreTable table. Delete these tables or add them to the ModuleIgnoreTable table.
  • Added an unnecessary TextStyle table to the merge module. If your merge module has no UI (and it generally should not) you can safely delete this table.
  • Added unnecessary entries to the Directory table. Remove unnecessary entries from the Directory table.
  • Left out the merge module's _Validation table this table incomplete. This prevents merge module validation. Add a complete _Validation table.

See Also

Authoring User Interfaces in Merge Modules, Authoring Merge Module Directory Tables, Validating Merge Modules


Obtaining Blank Merge Module Databases

[This is preliminary documentation and subject to change.]

Obtain a blank merge module database. You can use the file Schema.msm provided with the Windows Installer SDK as a starting database for your merge module. For more information, see Platform SDK Components for Windows Installer Developers.

Developers should author merge modules using the simplest database schema that installs their components. The use of a simple schema ensures the greatest compatibility for the merge module. Merging a merge module into an installation package with a different database schema usually results in merge conflicts.

For a complete list of all the required and optional tables in merge modules, see Merge Module Database Tables.


Naming Primary Keys in Merge Module Databases

[This is preliminary documentation and subject to change.]

The names of primary keys a merge module database must adhere to a standard naming convention. The purpose of this naming convention is to reduce the possibility of creating a name conflict between the table columns in the merge module and the target installation package.

The name of a primary key in a merge module must consist of a readable name appended with a string made from the merge module's GUID. Every merge module must have its own GUID. The merge module's GUID should also be authored into the Revision Number summary property of the merge module. Developers can create GUIDs using a utility such as GUIDGEN.

The following procedure describes how to generate a primary database key that adheres to the standard naming convention.

To name a primary key of a table record in a merge module

  1. Author the readable part of the name for the primary key. Pick a readable name that identifies this record, for example, MyRowEntry.
  2. Generate or obtain the GUID of the merge module. Note that all GUIDs must be authored in uppercase. For more information about GUIDs see GUID. The following is an example of a GUID: {880DE2F0-CDD8-11D1-A849-006097ABDE17}. In the following steps you modify this into a character string that must be appended to every primary key name in the merge module.
  3. Remove the curly braces from the beginning and end of the GUID.
  4. Change all the dashes to underscores.
  5. Append the result to the end of the readable part of the primary key name. Separate the readable name from the modified GUID by a period. The primary key name for the example GUID given above becomes MyRowEntry.880DE2F0_CDD8_11D1_A849_006097ABDE17.
  6. Repeat to name all the primary keys of all tables in the merge module.


Authoring Merge Module Component Tables

[This is preliminary documentation and subject to change.]

A Component table is required in every merge module. This table contains a record for each component delivered by the merge module to the target .msi file. Note that each of these components must also be specified in the ModuleComponents table described in Authoring ModuleComponents Tables.

Note that a merge module should never deliver a component containing system files to the main feature of an application because this may cause the installer to validate and repair the application each time the system file is used. An .msi file that is intended to accept components from a merge module should be authored such that any components containing system files only belong to features that are separate from the main feature of the application.

Use the standard naming convention when entering names into the Component column to ensure that the identifier for each component is unique for all merge modules and installation databases. For more information, see Naming Primary Keys in Merge Module Databases.

Complete the remaining fields in each record as described for an installation database in Component table. The components added to a package by a merge module must adhere to the guidelines for valid Windows Installer Components described in the following sections:

  • Windows Installer Components
  • Organizing Applications into Components


Referencing Features in Merge Modules

[This is preliminary documentation and subject to change.]

Merge modules only operate with components and not with features. However, some tables in merge modules, such as the PublishComponent table, contain fields that refer to features.

A null GUID: {00000000-0000-0000-0000-000000000000} must be authored into any field of a merge module database that references a feature. When the merge module is merged into an installation package, the merge tool replaces the null GUID with the feature specified in the installation package, except for tables that require special handling, such as the ModuleSignature table and the ModuleSequence tables.

Note that if a null GUID is used as a primary key, it is not guaranteed that the value substituted by the merge tool is unique. Authors of merge modules are responsible for ensuring that no existing primary key in the user's interface is duplicated when the merge tool replaces null GUIDs with features.


Authoring Merge Module Directory Tables

[This is preliminary documentation and subject to change.]

A merge module can be applied to a .msi file to add directories to the installation but it cannot replace or remove any existing directories. The Directory table specifies the layout of the directories the merge module provides to the target installation. A Directory table is required in every merge module.

Use the following guidelines when authoring the Directory Table in a merge module. For more information, see Directory Table and Using The Directory Table.

  • The directory structure added by the merge module must have a single root directory. The root must be named TARGETDIR. The user may change the value of TARGETDIR during the merge to specify where to attach the module's directory structure onto the target's directory tree.
  • Merge module tables other than the Directory table must not directly reference directory locations to TARGETDIR. The location of such a reference changes if the value of TARGETDIR is changed by the user.
  • The tables in the merge module must reference the location of a child directory of TARGETDIR, or another directory in the merge module's tree. Do the following to specify TARGETDIR as the parent of a directory in the merge module. Enter the directory into the Directory column and enter TARGETDIR into the Directory_Parent column. Use the "." notation in the DefaultDir column to indicate that this directory is located in TARGETDIR without a subdirectory. For more information, see Using the Directory Table.
  • The names of directories added by the merge module must use the naming conventions described in Naming Primary Keys in Merge Module Databases. This includes directories predefined by properties such as the SystemFolder property and ProgramFilesFolder property.
  • When a predefined directory is included in a merge module, the merge tool automatically adds a Custom Action Type 51 to the target database. The merge module author must ensure that a CustomAction table is also included. The CustomAction table may be empty, but this table is required to exist in the target database and ensures that the modified predefined directories are written to the correct locations. For example, when a system directory is included in a merge module, the merge module author must ensure that a Custom Action table exists.
  • Append a GUID to every entry in the Directory table. This includes Directory Table entries that specify a Windows Installer system folder properties, for example, SystemFolder.00000000_0000_0000_0000_000000000000. The library Mergemod.dll adds custom actions to set the SystemFolder property.

The following is an example of a Directory table in a merge module and the expected resolved directories.

Directory | Directory_Parent | DefaultDir
TARGETDIR |  | SourceDir
Dir00.BC82E350_ C7FC_11d1_ A848-006097ABDE17 | TARGETDIR | .:MMM_Prog
SystemFolder.BC82E350_ C7FC_11d1_ A848-006097ABDE17 | TARGETDIR | MMM_Sys
Dir02.BC82E350_ C7FC_11d1_ A848-006097ABDE17 | Dir00.BC82E350_ C7FC_11d1_ A848_006097ABDE17 | MFC_OCX

A merge module with the above Directory table is expected to result in the following directory structure.

Directory | Target | Source
Dir00.BC82E350_ C7FC_11d1_ A848-006097ABDE17 | [Merge Module's Install Point]\ | [Merge Module's Source Point]\MMM_Prog
SystemFolder.BC82E350_ C7FC_11d1_ A848-006097ABDE17 | [SystemFolder]\ | [Merge Module's Source Point]\MMM_Sys
Dir02.BC82E350_ C7FC_11d1_ A848-006097ABDE17 | [Merge Module's Install Point]\MFC_OCX | [Merge Module's Source Point]\MMM_Prog\MFC_OCX


Authoring Merge Module FeatureComponents Tables

[This is preliminary documentation and subject to change.]

A blank FeatureComponents table is required in every merge module. This empty table provides a schema for the merge tool if the target .msi file does not have its own FeatureComponents table.

If, and only if, there is no FeatureComponents table in the target .msi file does the merge tool use the blank table provided in the module. In this case, the merge tool creates a duplicate table in the target .msi file and adds rows that associate the new components in the merge module to the features in the application's installation package.


Generating MergeModule.CABinet Cabinet Files

[This is preliminary documentation and subject to change.]

Every file that is delivered to the target installation package by the merge module must be stored inside of a cabinet file embedded as a stream inside the .msm file. The name of this cabinet is always MergeModule.CABinet.

The names of files in MergeModule.CABinet must match the primary keys used in the merge module's File table and must adhere to the convention described in Naming Primary Keys in Merge Module Databases.

The installer skips extra files included in MergeModule.CABinet that are not listed in the merge module's File table. The sequence numbers of files specified in the File table do not need to be consecutive, but they must follow the same sequence as the files stored inside MergeModule.CABinet. For more information, see Authoring Merge Module File Tables.

This means that a single cabinet file can contain all the files needed for a merge module to support multiple languages. All the language files can be given unique sequence numbers in the cabinet and then a language transform can be used to add or remove files from the File table to obtain a merge module for a particular language. For details, see Authoring Multiple Language Merge Modules.

MergeModule.CABinet can be added to the merge module by opening a temporary _Streams Table. For example, the tool Msidb.exe provided with the Windows Installer SDK can be used to add the MergeModule.CABinet to the merge module. For more information, see Including a Cabinet File in an Installation.


Authoring Merge Module File Tables

[This is preliminary documentation and subject to change.]

A File table is required in every merge module. The File table should have a record for each file being delivered to the target installation package by the merge module. When the merge module is merged into a .msi file, every file in the merge module File table is stored inside of a cabinet file in the .msm file. The name of this cabinet in a merge module is always: MergeModule.CABinet. For more information, see also Generating MergeModule.CABinet Cabinet Files.

  • Because the files of a merge module are always stored inside a cabinet file, it is not necessary to set the msidbFileAttributesNoncompressed or msidbFileAttributesCompressed bit flags in the Attributes column of the File table.
  • The names of files in MergeModule.CABinet must match the primary key in the merge module's File table. Note that the File column is the primary key of the File Table and that the entries in this field must follow the convention described in Naming Primary Keys in Merge Module Databases.
  • File sequence numbers are specified in the Sequence column of the File table. Files must be listed in the merge module's File table in the same sequence as they are stored in MergeModule.CABinet. The sequence numbers of files do not need to be consecutive, but they must follow the same sequence of the files stored inside the cabinet. For example, the first, second, and third files stored in the cabinet can have the sequence numbers 100, 200, and 300.
  • The installer skips extra files included in MergeModule.CABinet that are not listed in the File table. This means that a single cabinet file can contain all the files necessary for a merge module supporting multiple languages using transforms. All the language files can be given a unique sequence number in the cabinet and then a transform can add or remove files from the File table as needed for a particular language. For more information, see Authoring Multiple Language Merge Modules.

For information on how to populate the remaining fields in this table, see column descriptions in File table.


Authoring ModuleSignature Tables

[This is preliminary documentation and subject to change.]

The ModuleSignature table contains all the information needed to identify the merge module.

The ModuleID field is the primary key for this table and must follow the convention described in Naming Primary Keys in Merge Module Databases. For example, if the readable name of the merge module is MyLibrary and the GUID for the merge module is {880DE2F0-CDD8-11D1-A849-006097ABDE17}, the entry in the ModuleID column of the ModuleSignature table becomes MyLibrary.880DE2F0_CDD8_11D1_A849_006097ABDE17.

Enter the decimal identifier for the default language of the merge module into the Language field of the ModuleSignature table.

Enter the version of the merge module into the Version field.


Authoring ModuleComponents Tables

[This is preliminary documentation and subject to change.]

List the all the components delivered by the merge module in the ModuleComponents table. Note that the merge module's components are also specified in the Component table. For more information, see Authoring Merge Module Component Tables.


Authoring Merge Module Sequence Tables

[This is preliminary documentation and subject to change.]

Include the MergeModuleSequence tables in the .msm file if the merge module must modify the action sequence tables of the target .msi file. Merging does not add these tables to the .msi file. These tables only occur in merge modules.

If any of the ModuleSequence tables are present in an .msm file, an empty copy of the corresponding installer sequence table must also be authored into the merge module. For example, if a merge module contains a ModuleAdminExecuteSequence table, the merge module must also include an empty AdminExecuteSequence table. During a merge, these empty tables provide the merge tool with necessary schema guidelines.

When using standard actions in merge module sequence tables, the value in the Sequence column should be the recommended action sequence number for the standard action. See the suggested action sequences given below for the recommended sequence numbers in each sequence table. If the sequence number in the merge module sequence table differs from the sequence number for the same action in the .msi file, the merge tool uses the sequence number in the .msi file during the merge.

MergeModuleSequence table | Recommended action sequences
ModuleAdminUISequence | Suggested AdminUISequence
ModuleAdminExecuteSequence | Suggested AdminExecuteSequence
ModuleAdvtUISequence | Suggested AdvtUISequence
ModuleAdvtExecuteSequence | Suggested AdvtExecuteSequence
ModuleInstallUISequence | Suggested InstallUISequence
ModuleInstallExecuteSequence table | Suggested InstallExecuteSequence

If a standard action is used in the Action column of a merge module sequence table, the BaseAction and After columns of that record must be Null. If a custom action or dialog is entered into the Action column, the Sequence column must be Null.

The BaseAction column can contain a standard action, a custom action specified in the merge module's custom action table, or a dialog specified in the module's dialog table. The BaseAction column is a key into the Action column of this table. It cannot be a foreign key into another merge table or table in the .msi file. This means that every standard action, custom action, or dialog listed in the BaseAction column must also be listed in the Action column of another record in this table.


Authoring User Interfaces in Merge Modules

[This is preliminary documentation and subject to change.]

Merge modules rarely require a user interface. Releasing a merge module that contains both installable components and a user interface ultimately restricts the flexibility of the module user. Combining both components and UI into one module can prevent developers from using their own UI or from providing silent installations. A better alternative is to release two merge modules, one that silently installs the components and a second optional module that contains the UI. The module with the UI should list the component module in its ModuleDependency table. This method enables module authors to provide a UI without forcing it on developers.

When UI tables are used in merge modules they can be merged in the same way as any other tables.


Authoring Merge Module Registry Tables

[This is preliminary documentation and subject to change.]

Use Merge Module Registry tables according to the type of registry information.

TypeLib, Class, AppId, ProgId, Extension, Verb, or MIME Tables

For type libraries, classes, extensions, and verbs, author registry information into the merge module's TypeLib, Class, AppId, ProgId, Extension, Verb, or MIME tables. If you use the Registry table to add this information, Windows 2000 cannot provide system-wide advertisement for these components.

Merge module authors may decide not to register using the Class table for the following reasons:

  • To be registered by the Class table, the file has to be the KeyPath of its component. This may require an unacceptable change in the organization of components.
  • A COM call may trigger an installer attempt to reinstall an advertised class. Authors may decide not to register a class using the Class table in order to avoid triggering a reinstallation when the client computer does not support a user interface.

Registry Table

Use the Registry table to add registry information that cannot be authored into the TypeLib, Class, AppId, ProgId, Extension, Verb, or MIME tables. Windows 2000 cannot provide system-wide advertisement for components that use the Registry table.

When authoring the Registry Table, refer to file paths using the [#File] or [!File] format rather than as [Directory]Filename. The latter format does not support run-from-source installation. The former format also makes missing files and faulty components easier to detect.

Care is needed when using formatted text in the Key column of the Registry table. Because Windows Installer does not reinstall components that are already installed, using formatted text in this field may cause registry keys to be left behind on application removal.

SelfReg Table

Using the SelfReg table is not recommended. For a list of reasons for not using self-registration, see SelfReg table. You should use the TypeLib, Class, AppId, ProgId, Extension, Verb, and MIME tables where possible instead and the Registry table in all other cases.


Authoring Merge Module Summary Information Streams

[This is preliminary documentation and subject to change.]

Every merge module is required to have a Merge Module Summary Information Stream with the following summary information properties:

  • Template summary property
  • Revision Number summary property
  • Page Count summary property
  • Word Count summary property

For a complete list of summary information properties in merge modules, see Merge Module Summary Information Stream Reference.


Validating Merge Modules

[This is preliminary documentation and subject to change.]

Authors should run validation on every new, or newly modified, merge module before attempting to merge the module into an installation database for the first time. Merge module validation works in the same way as package validation but uses a different set of Internal Consistency Evaluators (ICEs) specific to merge modules. For more information about these merge module ICEs, see Merge Module ICE Reference.

Merge module ICEs are stored in the merge module .cub file, Mergemod.cub. With Windows Installer version 1.1 SDK or later, the installation of the Orca tool or msival2 also provides the Logo.cub, Darice.cub, and Mergemod.cub files.

For more information, see Merge Module ICE Reference.


Adding Readme Information Streams to Merge Modules

[This is preliminary documentation and subject to change.]

A merge module must not include a readme information stream.


Authoring Multiple Language Merge Modules

[This is preliminary documentation and subject to change.]

The following sections discuss authoring multiple language merge modules in detail.

How do I choose the default language of a multiple-language merge module?

How do I author a language transform for a multiple-language merge module?

How do I order the file sequence in the CAB of a multiple language merge module?


How do I choose the default language of a multiple-language merge module?

[This is preliminary documentation and subject to change.]

The default language for a merge module is the language listed in the ModuleSignature table of the module before any language transforms are applied. This is also the first language listed in the Template Summary Property.

The default language for the module should be one of the most specific languages you support because the default language is always checked first, and if it satisfies the requested language, it is used, even if another language would be a better match. For example, if a module supports 1033 and 0, 1033 should be the default language. If 0 were the default language, it would always satisfy any request, so the 1033 transform would never be used, even if 1033 is the exactly language requested.


How do I author a language transform for a multiple-language merge module?

[This is preliminary documentation and subject to change.]

When a module is merged into an database that has a different default language, the merge tool may need to apply a language transform to the module to provide the final language. For more information, see Multiple Language Merge Modules.

The language transforms are stored in the module's .msm file and must have the name and format: MergeModule.Lang####. The #### represents the up-to four digit LANGID of the final language. For example, MergeModule.Lang1033, MergeModule.Lang9, and MergeModule.Lang0 for transforms to US English, world English, and language neutral.

The language transform should do the following:

  • Change the default language in the Language column of the ModuleSignature table to the new language of the module.
  • Change the default language in the Language column of the ModuleComponents table to the new language of the module. The transform may add or remove rows from this table.
  • If necessary, change the language in the RequiredLanguage column, or add or delete rows, to the ModuleDependency table.
  • If necessary, change the language in the ExcludedLanguage column, or add or delete rows, to the ModuleExclusion table.
  • The transform may perform any valid transform operations on the module, including adding or removing components, files, registry entries, or actions.

Note that applying a language transform when opening the module doesn't change the default language or the languages supported by the module, it just changes the language that is being requested. Therefore the Template property does not change, it should already list all of the languages supported by the module with the default language listed first.

All files needed by all possible language transforms are commonly stored in a single cabinet file included with the module. Because it is not practical to have the language transform modify this cabinet file, it is best to use a global file sequence in the cabinet file, File table, and language transform. For details, see How do I order the file sequence in the CAB of a multiple language merge module?


How do I order the file sequence in the CAB of a multiple language merge module?

[This is preliminary documentation and subject to change.]

Multiple-language merge modules, language transforms, and cabinet files must be authored such that the order of the files in the .cab matches the installation order of files specified in the File table, even after the application of the language transform. If the order in the module and in the .cab do not match, the merge module cannot be used.

Assign to each file in the module a unique sequence number that is independent of its language and then always use this sequence number for the file. Use this same sequence when building the cabinet file and when authoring a language transform.

Because the installer only installs the files listed in the File table, the use of a global file sequence in the cabinet, File table, and language transform enables the merge tool to skip any extra files stored in the cabinet that are not listed in the File table. Other files may exist in the cabinet as long as they are not listed in the File table.

For example, a module installing Code.dll, English.dat, German.dat, and French.dat can use the following global file sequence order

File | Sequence
Code.Dll | 1
English.Dat | 2
German.Dat | 3
French.Dat | 4

Language transforms can then be authored to modify the File table of the module for English, German, or French.

File Table (partial for English)

File | Sequence
Code.Dll | 1
English.Dat | 2

File Table (partial for German)

File | Sequence
Code.Dll | 1
German.Dat | 3

File Table (partial for French)

File | Sequence
Code.Dll | 1
French.Dat | 4

For more information, see Authoring Merge Module File Tables or How do I author a language transform for a multiple-language merge module?.


Applying Merge Modules

[This is preliminary documentation and subject to change.]

Merge modules must be merged into an installation package using a merge tool. The best alternative is to obtain a freely distributed merge tool or purchase one of the merging tools to be available from independent software vendors. For example you can use the functionality provided by Mergemod.dll.

Multiple-language merge modules can be opened in different languages and then merged into a target to produce a different language version of the package. For more information, see:

  • How do I open a multiple-language merge module in a specific language?
  • How do I merge a multiple language module into the same package multiple times?


How do I open a multiple-language merge module in a specific language?

[This is preliminary documentation and subject to change.]

When merging a module into an installation database, there are two languages of interest. The first is the language of the target installation package specified by ProductLanguage in the Property table. The second is the language of the merge module, which appears in the Language column of the ModuleSignature table.

The language of the installation package may be passed to the module by the merge tool when the package is opened for the merge. However, in some cases it may be necessary to disregard the language of the target and request that the module be opened in another language. For example, in the case of an English package installing both the English and German resources from the module.

When opening a module with a language request, the merge tool checks the requested language against the languages specified in the Language column of the ModuleSignature table. The following process is used to determine which language to use:

  1. If the language in the ModuleSignature table is equal or more general than the requested language, the module opens.
  2. If the module supports the exact language requested, that language is used.
  3. If the module supports the language group of the language requested that language group is used. For example, check 9 if 1033 was requested but not found in step 2.
  4. Check if there is a language transform that changes the module to neutral.
  5. If none of the above succeed, the module does not support the requested language and so the merge fails.


How do I merge a multiple language module into the same package multiple times?

[This is preliminary documentation and subject to change.]

When a module supports multiple languages, you can merge it into the same Windows Installer database multiple times, as long as each merge uses a different language. Before each merge, request a different language from the module. The resulting .msi database then has a record in the ModuleSignature table for each merge of the module. Components that are shared between languages exist only once in the Component table, but are associated with each language in the ModuleComponents table.

When merging multiple languages of a module into the same package, each merge must satisfy the same restrictions on code pages as single-language modules. The modules cannot contain strings in different code pages.

When merging a module multiple times into a single .msi file, you may need to modify the order of the files in the File table to use the existing .cab from the module directly in your installation. The order of files in the File table must match the order of files in the .cab. When merging a module multiple times into an installation database, the sequence may be modified because files shared between the languages may already exist in the module from the prior merge, and have a different relative sequence number.


Using Configurable Merge Modules

[This is preliminary documentation and subject to change.]

The following sections describe how merge module authors, module consumers, and merge tool developers may use configurable merge modules:

How do I create a merge module that can be configured by the end user?

How do I apply a configurable merge module with customizations?

How do I add module configuration capability to a merge tool?


How do I create a merge module that can be configured by the end user?

[This is preliminary documentation and subject to change.]

Follow the general guidelines for creating merge modules described in Authoring Merge Modules. In addition, authors must do the following to create a merge module that may be configured by the end user of the module:

  • Note that end users need to have Mergemod.dll version 1.5 to configure you module. Users having earlier versions of Mergemod.dll can apply the module as usual but always get the default settings.
  • Add a ModuleConfiguration Table to the merge module to identify the items that may be configured by an end user. Add a record in this table for each configurable item. These items are substituted into the templates specified in the ModuleSubstitution Table. Enter a name for each configurable item into the Name field. Enter the format, type, and semantic context for each item in the Format, Type, and ContextData columns. For more information about types, see Semantic Types. Enter a default value for the item in the DefaultValue field using the CMSM special format.
  • Add a ModuleSubstitution Table to the merge module. Each record of this table corresponds to a substitution of one or more configurable items into one field of the merge module database. Enter the table, row, and column of the field receiving the substitution. Enter a formatting template for the substitution into the Value column using the CMSM special format.
  • Add records to the _Validation table for the ModuleSubstitution and ModuleConfiguration tables.
  • Add records to the ModuleIgnoreTable table for the ModuleSubstitution and ModuleConfiguration tables. This ensures that the module is compatible for users who have versions of MergeMod.dll earlier than version 1.5.


How do I apply a configurable merge module with customizations?

[This is preliminary documentation and subject to change.]

Follow the general guidelines for applying merge modules described in Applying Merge Modules. In addition, merge module consumers must do the following to configure a merge module at the time of installation:

  • Use a merge module that has been authored to have configurable settings. For details, see How do I create a merge module that can be configured by the end user?
  • Use a merge and configuration tool that calls Mergemod.dll version 1.5 or later. Earlier versions of Mergmod.dll cannot configure merge module settings. Authors should create merge modules which provide default values and are compatible with earlier versions of Mergmod.dll.
  • Provide customization information when prompted by the configuration client tool. Authors should create merge modules which use default values when a user declines to provide information.


How do I add module configuration capability to a merge tool?

[This is preliminary documentation and subject to change.]

To enable end users to use configurable merge modules, developers should author merge and configuration tools to do the following:

  • Merge tools should call the functions in Mergemod.dll version 1.5 to merge the module. Earlier versions of Mergemod.dll cannot be used to configure merge modules.
  • Client configuration applications should interact with the merge module user to collect the user's selections for configurable items.
  • Merge tools should expose configuration information authored into the merge module to the client application so that the client may use this information to query the user.
  • When a merge tool encounters a configurable item during the merge, it should call the client configuration tool for customization information obtained from the user. The merge tool should make the specified changes to the merge module.
  • Configuration applications should enable the user to provide choices for configurable items, but they do not need to reveal all the possible choices to the user. It may use default values for configurable items not selected by the user.
  • If a user declines to provide customization information, merge tools should use the default configuration values specified in the merge module .
  • After the user gives the configuration tool his or her selections, the merge tool calls Mergemod.dll to perform the merge.


Merge Module Reference

[This is preliminary documentation and subject to change.]

This section contains detailed reference information about merge module database tables and summary information streams.

  • Merge Module Database Tables
  • Merge Module Summary Information Stream Reference


Merge Module Database Tables

[This is preliminary documentation and subject to change.]

The following tables are required in a standard merge module.

Table name | Comment
Component | (REQUIRED)
Directory | (REQUIRED)
FeatureComponents | (REQUIRED)
File | (REQUIRED)
ModuleSignature | (REQUIRED) Merged into the installer database. Lists the information identifying a merge module.
ModuleComponents | (REQUIRED) Merged into the installer database. Lists all the components in the merge module.

The following tables only occur in merge modules or other installer databases that have already been combined with a merge module.

Table name | Comment
ModuleDependency | Merged into the installer database. Lists other merge modules required by this merge module.
ModuleExclusion | Merged into the installer database. Lists other merge modules that are incompatible with this merge module.

The following ModuleSequence tables only occur in merge modules.

Table name | Comment
ModuleAdminUISequence | Merges actions into the AdminUISequence table.
ModuleAdminExecuteSequence | Merges actions into the AdminExecuteSequence table.
ModuleAdvtUISequence | Do not use this table. For details, see AdvtUISequence table.
ModuleAdvtExecuteSequence | Merges actions into the AdvtExecuteSequence table.
ModuleIgnoreTable | Lists tables in the module that are not merged into the .msi file.
ModuleInstallUISequence | Merges actions into the InstallUISequence table.
ModuleInstallExecuteSequence | Merges actions into the InstallExecuteSequence table.

The following tables are required in every configurable merge module. MergeMod.dll version 1.5 or later is required to create configurable merge module. For details, see Configurable Merge Modules.

Table name | Comment
ModuleSubstitution Table | (REQUIRED) This table is not merged into the target installation database. Specifies the configurable fields in the target database and provides a template for the configuration of each field.
ModuleConfiguration Table | (REQUIRED) This table is not merged into the target installation database. Identifies the configurable attributes of the module.

The following installer tables cannot occur in a standard merge module.

BBControl
Billboard
CCPSearch
Error
Feature
LaunchCondition table
Media
Patch
Upgrade

The following installer tables are optional in merge modules.

ActionText
AdminExecuteSequence
AdminUISequence
AdvtExecuteSequence
AdvtUISequence
AppId
AppSearch
BindImage
CheckBox
Class
ComboBox
CompLocator
Control
ControlCondition
CreateFolder
CustomAction
Dialog
DrLocator
DuplicateFile
Environment
EventMapping
Extension
Font
Icon
IniFile
IniLocator
InstallExecuteSequence
InstallUISequence
ListBox
ListView
MIME
MoveFile
ODBCAttribute
ODBCDataSource
ODBCDriver
ODBCSourceAttribute
ODBCTranslator
ProgID Table
Property
PublishComponent
RadioButton
Registry Table
RegLocator
RemoveFile
RemoveIniFile
RemoveRegistry
ReserveCost
SelfReg
ServiceControl
ServiceInstall
Shortcut
Signature
TextStyle
TypeLib
UIText
Verb


ModuleSignature Table

[This is preliminary documentation and subject to change.]

The ModuleSignature Table is a required table. It contains all the information necessary to identify a merge module. The merge tool adds this table to the .msi file if one does not already exist. The ModuleSignature table in a merge module has only one row containing the ModuleID, Language, and Version. However, the ModuleSignature table in an .msi file has a row containing this information for each .msm file that has been merged into it.

Merge and verification tools check the ModuleSignature table in .msi files to determine if it has all of the dependent merge modules required by the current merge module (see ModuleDependency Table) and whether the installation package was previously merged with any conflicting merge modules (see ModuleExclusion Table).

The ModuleSignature table has the following columns.

Column | Type | Key | Nullable
ModuleID | Identifier | Y | N
Language | Integer | Y | N
Version | Version |  | N

Columns

ModuleID
An identifier that uniquely identifies the merge module. Two merge modules cannot have the same ModuleID unless the merge module is entirely backward compatible with its predecessor. You can create a GUID for this field using a utility such as GUIDGEN. The ModuleID column is a primary key for the table and therefore it must follow the naming convention in Naming Primary Keys in Merge Module Databases. For example, if the readable name of the merge module is MyLibrary and the GUID is {880DE2F0-CDD8-11D1-A849-006097ABDE17}, the entry in the ModuleID column becomes MyLibrary.880DE2F0_CDD8_11D1_A849_006097ABDE17.
Language
The Language identifier specifies the default language for the merge module. The language identifier is in decimal format, for example, U.S. English is 1033. The language used by the merge module can be changed by applying a transform to the merge module before merging.
Version
The Version field contains a string that describes the major and minor versions of the merge module.


ModuleComponents Table

[This is preliminary documentation and subject to change.]

The ModuleComponents table contains a list of the components found in the merge module.

The ModuleComponents table has the following columns.

Column | Type | Key | Nullable
Component | Identifier | Y | N
ModuleID | Identifier | Y | N
Language | Integer | Y | N

Columns

Component
An identifier referring to a component in the merge module. The Component column is a foreign key to the Component table. The entry in the Component column must follow the naming convention in Naming Primary Keys in Merge Module Databases.
ModuleID
The identifier for the merge module. This is a foreign key to the ModuleSignature table.
Language
The Language identifier describes the default language for the merge module. The language identifier is in decimal format, for example, U.S. English is 1033. Foreign key to the ModuleSignature table.

Remarks

Language transforms must be able to update this table if the merge module supports multiple languages.


ModuleDependency Table

[This is preliminary documentation and subject to change.]

The ModuleDependency table keeps a list of other merge modules that are required for this merge module to operate properly. This table enables a merge or verification tool to ensure that the necessary merge modules are in fact included in the user's installer database. The tool checks by cross referencing this table with the ModuleSignature table in the installer database.

The ModuleDependency table has the following columns.

Column | Type | Key | Nullable
ModuleID | Identifier | Y | N
ModuleLanguage | Integer | Y | N
RequiredID | Identifier | Y | N
RequiredLanguage | Integer | Y | N
RequiredVersion | Version |  | Y

Columns

ModuleID
Identifier of the merge module. This is a foreign key into the ModuleSignature table.
ModuleLanguage
Decimal language ID of the merge module in ModuleID. This is a foreign key into the ModuleSignature table.
RequiredID
Identifier of the merge module required by the merge module in ModuleID.
RequiredLanguage
Numeric language ID of the merge module in RequiredID. The RequiredLanguage column can specify the language ID for a single language, such as 1033 for U.S. English, or specify the language ID for a language group, such as 9 for any English. If the field contains a group language ID, any merge module with having a language code in that group satisfies the dependency. If the RequiredLanguage is set to 0, any merge module filling the other requirements satisfies the dependency.
RequiredVersion
Version of the merge module in RequiredID. If this field is Null, any version fills the dependency.


ModuleExclusion Table

[This is preliminary documentation and subject to change.]

The ModuleExclusion table keeps a list of other merge modules that are incompatible in the same installer database. This table enables a merge or verification tool to check that conflicting merge modules are not merged in the user's installer database. The tool checks by cross-referencing this table with the ModuleSignature table in the installer database.

The ModuleExclusion table has the following columns.

Column | Type | Key | Nullable
ModuleID | Identifier | Y | N
ModuleLanguage | Integer | Y | N
ExcludedID | Identifier | Y | N
ExcludedLanguage | Integer | Y | N
ExcludedMinVersion | Version |  | Y
ExcludedMaxVersion | Version |  | Y

Columns

ModuleID
Identifier of the merge module. This is a foreign key into the ModuleSignature table.
ModuleLanguage
Decimal language ID of the merge module in ModuleID. This is a foreign key into the ModuleSignature table.
ExcludedID
Identifier of an excluded merge module.
ExcludedLanguage
Numeric language ID of the merge module in ExcludedID. The ExcludedLanguage column can specify the language ID for a single language, such as 1033 for U.S. English, or specify the language ID for a language group, such as 9 for any English. The ExcludedLanguage column can accept negative language IDs. The meaning of the value in the ExcludedLanguage column is as follows.
ExcludedLanguage | Meaning
> 0 | Exclude the language IDs specified by ExcludedLanguage.
= 0 | Exclude no language IDs.
< 0 | Exclude all language IDs except those specified by ExcludedLanguage.

ExcludedMinVersion
Minimum version excluded from a range. If the ExcludedMinVersion field is Null, all versions before ExcludedMaxVersion are excluded. If both ExcludedMinVersion and ExcludedMaxVersion are Null there is no exclusion based on version.
ExcludedMaxVersion
Maximum version excluded from a range. If the ExcludedMaxVersion field is Null, all versions after ExcludedMinVersion are excluded. If both ExcludedMinVersion and ExcludedMaxVersion are Null there is no exclusion based on version.


ModuleAdminUISequence Table

[This is preliminary documentation and subject to change.]

A merge tool evaluates the ModuleAdminUISequence table and then inserts the calculated actions into the AdminUISequence table with a correct sequence number.

The ModuleAdminUISequence table has the following columns.

Column | Type | Key | Nullable
Action | Identifier | Y | N
Sequence | Integer |  | N
BaseAction | Identifier |  | Y
After | Integer |  | Y
Condition | Condition |  | Y

Columns

Action
Action to insert into sequence. Refers to one of the installer standard actions, or an entry in the merge module's CustomAction table or Dialog table.

If a standard action is used in the Action column of a merge module sequence table, the BaseAction and After columns of that record must be Null.

Sequence
The sequence number of a standard action. If a custom action or dialog is entered into the Action column of this row, this field must be set to Null.

When using standard actions in merge module sequence tables, the value in the Sequence column should be the recommended action sequence number. If the sequence number in the merge module differs from that for the same action in the .msi file sequence table, the merge tool uses the sequence number from the .msi file. See the suggested sequences in Using a Sequence Table for the recommended sequence numbers of standard actions.

BaseAction
The BaseAction column can contain a standard action, a custom action specified in the merge module's custom action table, or a dialog specified in the module's dialog table. The BaseAction column is a key into the Action column of this table. It cannot be a foreign key into another merge table or table in the .msi file. This means that every standard action, custom action, or dialog listed in the BaseAction column must also be listed in the Action column of another record in this table.
After
Boolean for whether Action comes before or after BaseAction.
Value | Meaning
0 | Action to come before BaseAction
1 | Action to come after BaseAction

Condition
A conditional statement that indicates if the action is be executed. Null evaluates to true.

Remarks

If this table is present the AdminUISequence Table must also be present in the merge module.


ModuleAdminExecuteSequence Table

[This is preliminary documentation and subject to change.]

A merge tool evaluates the ModuleAdminExecuteSequence table and then inserts the calculated actions into the AdminExecuteSequence table with a correct sequence number.

The ModuleAdminExecuteSequence table has the following columns.

Column | Type | Key | Nullable
Action | Identifier | Y | N
Sequence | Integer |  | N
BaseAction | Identifier |  | Y
After | Integer |  | Y
Condition | Condition |  | Y

Columns

Action
Action to insert into sequence. Refers to one of the installer standard actions, or an entry in the merge module's CustomAction table or Dialog table.

If a standard action is used in the Action column of a merge module sequence table, the BaseAction and After columns of that record must be Null.

Sequence
The sequence number of a standard action. If a custom action or dialog is entered into the Action column of this row, this field must be set to Null.

When using standard actions in merge module sequence tables, the value in the Sequence column should be the recommended action sequence number. If the sequence number in the merge module differs from that for the same action in the .msi file sequence table, the merge tool uses the sequence number from the .msi file. See the suggested sequences in Using a Sequence Table for the recommended sequence numbers of standard actions.

BaseAction
The BaseAction column can contain a standard action, a custom action specified in the merge module's custom action table, or a dialog specified in the module's dialog table. The BaseAction column is a key into the Action column of this table. It cannot be a foreign key into another merge table or table in the .msi file. This means that every standard action, custom action, or dialog listed in the BaseAction column must also be listed in the Action column of another record in this table.
After
Boolean for whether Action comes before or after BaseAction.
Value | Meaning
0 | Action to come before BaseAction
1 | Action to come after BaseAction

Condition
A conditional statement that indicates if the action is be executed. Null evaluates to true.

Remarks

If this table is present the AdminExecuteSequence table must also be present in the merge module.


ModuleAdvtUISequence Table

[This is preliminary documentation and subject to change.]

Do not author this table. The Windows Installer does not use the AdvtUISequence table. The AdvtUISequence table should not exist or should be left blank in the installation database. Also do not author the ModuleAdvtUISequence table.


ModuleAdvtExecuteSequence Table

[This is preliminary documentation and subject to change.]

A merge tool evaluates the ModuleAdvtExecuteSequence table and then inserts the calculated actions into the AdvtExecuteSequence table with a correct sequence number.

The ModuleAdvtExecuteSequence table has the following columns.

Column | Type | Key | Nullable
Action | Identifier | Y | N
Sequence | Integer |  | N
BaseAction | Identifier |  | Y
After | Integer |  | Y
Condition | Condition |  | Y

Columns

Action
Action to insert into sequence. Refers to one of the installer standard actions, or an entry in the merge module's CustomAction table or Dialog table.

If a standard action is used in the Action column of a merge module sequence table, the BaseAction and After columns of that record must be Null.

Sequence
The sequence number of a standard action. If a custom action or dialog is entered into the Action column of this row, this field must be set to Null.

When using standard actions in merge module sequence tables, the value in the Sequence column should be the recommended action sequence number. If the sequence number in the merge module differs from that for the same action in the .msi file sequence table, the merge tool uses the sequence number from the .msi file. See the suggested sequences in Using a Sequence Table for the recommended sequence numbers of standard actions.

BaseAction
The BaseAction column can contain a standard action, a custom action specified in the merge module's custom action table, or a dialog specified in the module's dialog table. The BaseAction column is a key into the Action column of this table. It cannot be a foreign key into another merge table or table in the .msi file. This means that every standard action, custom action, or dialog listed in the BaseAction column must also be listed in the Action column of another record in this table.
After
Boolean for whether Action comes before or after BaseAction.
Value | Meaning
0 | Action to come before BaseAction
1 | Action to come after BaseAction

Condition
A conditional statement that indicates if the action is be executed. Null evaluates to true.

Remarks

If this table is present the AdvtExecuteSequence table must also be present in the merge module.


ModuleIgnoreTable Table

[This is preliminary documentation and subject to change.]

If a table in the merge module is listed in the ModuleIgnoreTable table, it is not merged into the .msi file. If the table already exists in the .msi file, it is not modified by the merge. The tables in the ModuleIgnoreTable can therefore contain data that is unneeded after the merge.

The ModuleIgnoreTable table has the following columns.

Column | Type | Key | Nullable
Table | Identifier | Y | No

Columns

Table
Name of the table in the merge module that is not to be merged into the .msi file.

Remarks

To minimize the size of the .msm file, it is recommended that developers remove unused tables from modules intended for redistribution rather than listing these tables in the ModuleIgnoreTable table.


ModuleInstallUISequence Table

[This is preliminary documentation and subject to change.]

A merge tool evaluates the ModuleInstallUISequence table and then inserts the calculated actions into the InstallUISequence table with a correct sequence number.

The ModuleInstallUISequence table has the following columns.

Column | Type | Key | Nullable
Action | Identifier | Y | N
Sequence | Integer |  | N
BaseAction | Identifier |  | Y
After | Integer |  | Y
Condition | Condition |  | Y

Columns

Action
Action to insert into sequence. Refers to one of the installer standard actions, or an entry in the merge module's CustomAction table or Dialog table.

If a standard action is used in the Action column of a merge module sequence table, the BaseAction and After columns of that record must be Null.

Sequence
The sequence number of a standard action. If a custom action or dialog is entered into the Action column of this row, this field must be set to Null.

When using standard actions in merge module sequence tables, the value in the Sequence column should be the recommended action sequence number. If the sequence number in the merge module differs from that for the same action in the .msi file sequence table, the merge tool uses the sequence number from the .msi file. See the suggested sequences in Using a Sequence Table for the recommended sequence numbers of standard actions.

BaseAction
The BaseAction column can contain a standard action, a custom action specified in the merge module's custom action table, or a dialog specified in the module's dialog table. The BaseAction column is a key into the Action column of this table. It cannot be a foreign key into another merge table or table in the .msi file. This means that every standard action, custom action, or dialog listed in the BaseAction column must also be listed in the Action column of another record in this table.
After
Boolean for whether Action comes before or after BaseAction.
Value | Meaning
0 | Action to come before BaseAction
1 | Action to come after BaseAction

Condition
A conditional statement that indicates if the action is be executed. Null evaluates to true.

Remarks

If this table is present the InstallUISequence table must also be present in the merge module.


ModuleInstallExecuteSequence Table

[This is preliminary documentation and subject to change.]

A merge tool evaluates the ModuleInstallExecuteSequence table and then inserts the calculated actions into the InstallExecuteSequence table with a correct sequence number.

The ModuleInstallExecuteSequence table has the following columns.

Column | Type | Key | Nullable
Action | Identifier | Y | N
Sequence | Integer |  | N
BaseAction | Identifier |  | Y
After | Integer |  | Y
Condition | Condition |  | Y

Columns

Action
Action to insert into sequence. Refers to one of the installer standard actions, or an entry in the merge module's CustomAction table or Dialog table.

If a standard action is used in the Action column of a merge module sequence table, the BaseAction and After columns of that record must be Null.

Sequence
The sequence number of a standard action. If a custom action or dialog is entered into the Action column of this row, this field must be set to Null.

When using standard actions in merge module sequence tables, the value in the Sequence column should be the recommended action sequence number. If the sequence number in the merge module differs from that for the same action in the .msi file sequence table, the merge tool uses the sequence number from the .msi file. See the suggested sequences in Using a Sequence Table for the recommended sequence numbers of standard actions.

BaseAction
The BaseAction column can contain a standard action, a custom action specified in the merge module's custom action table, or a dialog specified in the module's dialog table. The BaseAction column is a key into the Action column of this table. It cannot be a foreign key into another merge table or table in the Windows Installer file. This means that every standard action, custom action, or dialog listed in the BaseAction column must also be listed in the Action column of another record in this table.
After
Boolean for whether Action comes before or after BaseAction.
Value | Meaning
0 | Action to come before BaseAction
1 | Action to come after BaseAction

Condition
A conditional statement that indicates if the action is be executed. Null evaluates to true.

Remarks

If this table is present the InstallExecuteSequence table must also be present in the merge module.


ModuleSubstitution Table

[This is preliminary documentation and subject to change.]

The ModuleSubstitution table specifies the configurable fields of a module database and provides a template for the configuration of each field. The user or merge tool may query this table to determine what configuration operations are to take place. This table is not merged into the target database.

The following tables cannot contain configurable fields and must not be listed in this table:

ModuleSubstitution table

ModuleConfiguration table

ModuleExclusion table

ModuleSignature table

The ModuleSubstitution table has the following columns.

Column | Type | Key | Nullable
Table | Identifier | Y | N
Row | Text | Y | N
Column | Identifier | Y | N
Value | Text | N | Y

Columns

Table
This column specifies the name of the table being modified in the module database.
Row
This field specifies the primary keys of the target row in the table named in the Table column. Multiple primary keys are separated by semicolons. Target rows are selected for modification before any changes are made to the target table. If one record in the ModuleSubstitution table changes the primary key field of a target row, other records in the ModuleSubstitution table are applied based on the original primary key data, not the resulting of primary key substitutions. The order of row substitution is undefined.

Values in this column are always in CMSM special format. A literal semicolon (';') or equal sign ('=') can be added by prefixing the character with a backslash. '\'. A NULL value for a key is signified by a NULL, a leading semicolon, two consecutive semicolons, or a trailing semicolon, depending on whether the NULL value is a sole, first, middle, or final key column value.

Column
This field specifies the target column in the row named in the Row column. If multiple rows in the ModuleSubstitution table change different columns of the same target row, all the column substitutions are performed before the modified row is inserted into the database. The order of column substitution is undefined.
Value
This column contains a string that provides a formatting template for the data being substituted into the target field specified by Table, Row, and Column. When a substitution string of the form [=ItemA] is encountered, the string, including the bracket characters, is replaced by the value for the configurable "ItemA." The configurable item "ItemA" is specified in the Name column of the ModuleConfiguration table and its value is provided by the merge tool. If the merge tool declines to provide a value for any item in a replacement string, the default value specified in the DefaultValue column of the ModuleConfiguration Table is substituted. If a string references an item not in the ModuleConfiguration table, the merge fails.
  • This column uses CMSM special format. A literal semicolon (';') or equals sign ('=') can be added to the table by prefixing the character with a backslash. '\'.
  • The Value field may contain multiple substitution strings. For example, the configuration of items "Food1" and "Food2" in the string: "[=Food1] is good, but [=Food2] is better because [=Food2] is more nutritious."
  • Replacement strings must not be nested. The template "[=AB[=CDE]]" is invalid.
  • If the Value field evaluates to NULL, and the target field is not nullable, the merge fails and an error object of type msmErrorBadNullSubstitution is created and added to the error list. For details, see the error types described in get_Type Function.
  • If the Value field evaluates to the null GUID: {00000000-0000-0000-0000-000000000000}, the null GUID is replaced by the name of the feature before the row is merged into the module. For details, see Referencing Features in Merge Modules.
  • The template in the Value field is evaluated before being inserted into the target field. Substitution into a row is done before replacing any features.
  • If the Value column evaluates to a string of only integer characters (with an optional + or -), the string is converted into an integer before being substituted into an target field of the Integer Format Type. If the template evaluates to a string that does not consist only of integer characters (and an optional + or -) the result cannot be substituted into an integer target field. Attempting to insert a non-integer into an integer field causes the merge to fail and adds a msmErrorBadSubstitutionType error object to the error list.
  • If the target column specified in the Table and Column fields is a Text Format Type, and evaluation of the Value field results in an Integer Format Type, a decimal representation of the number is inserted into the target text field.
  • If the target field is an Integer Format Type, and the Value field consists of a non-delimited list of items in Bitfield Format, the value in the target field is combined using the bitwise AND operator with the inverse of the bitwise OR of all of the mask values from the items, then combined using the bitwise OR operator with each of the integer or bitfield items when masked by their corresponding mask values. Essentially, this explicitly sets the bits from the properties to the provided values but leaves all other bits in the cell alone.
  • If the Value field evaluates to a Key Format Type, and is a key into a table that uses multiple primary keys, the item name may be followed by a semicolon and an integer value that indicates the 1-based index into the set of values that together make a primary key. If no integer is specified, the value 1 is used. For example, the Control table has two primary key columns, Dialog_ and Control. The value of an item "Item1" that is a key into the Control table will be of the form "DialogName;ControlName", where DialogName is the value in the Dialog_ table and ControlName is the value in the Control column. To substitute just ControlName, the substitution string [=Item1;2] should be used.

Remarks

The ModuleSubstition table is used by Configurable Merge Modules. MergeMod.dll version 1.5 or later is required to create a configurable merge module.

To ensure compatibility with versions of MergeMod.dll earlier than version 1.5, the ModuleConfiguration table and ModuleSubstitution tables should be included in the ModuleIgnoreTable table of every module.


ModuleConfiguration Table

[This is preliminary documentation and subject to change.]

The ModuleConfiguration table identifies the configurable attributes of the module. This table is not merged into the database.

The ModuleConfiguration table has the following columns.

Column | Type | Key | Nullable
Name | Identifier | Y | N
Format | Integer | N | N
Type | Text | N | Y
ContextData | Text | N | Y
DefaultValue | Text | N | Y
Attributes | Integer | N | Y
DisplayName | Text | N | Y
Description | Text | N | Y
HelpLocation | Text | N | Y
HelpKeyword | Text | N | Y

Columns

Name
This field defines the name of the configurable item. This name is referenced in the formatting template in the Value column of the ModuleSubstitution table.
Format
This column specifies the format of the data being changed.
Format | Value
Text | 0
Key | 1
Integer | 2
Bitfield Format | 3

Type
This column specifies the type for the data being changed. This type is used to provide a context for any user-interface and is not used in the merge process. The valid values for this column depend on the value in the Format column.
ContextData
This column specifies a semantic context for the requested data. The type is used to provide a context for any user-interface and is not used in the merge process. The valid values for this column depend on the values in the Format and Type columns.
DefaultValue
This column specifies a default value for the item in this record if the merge tool declines to provide a value. This value must have the format, type, and context of the item. If this is a "Key" format item, the foreign key must be a valid key into the tables of the module. NULL may be a valid value for this column depending on the item. For "Key" format items, this value is in CMSM special format. For all other types, the value is treated literally.

Module authors must ensure that the module is valid in its default state. This ensures that versions of MergeMod.dll earlier than version 1.5 can still use the module in its default state.

Attributes
This column is a bit field containing attributes for this configurable item. NULL is equivalent to 0. All other bits in this column are reserved for future use and must be 0.
Name | Decimal | Hexadecimal | Description
msmConfigItemKeyNoOrphan 1 0x00000001 This attribute only applies to records that list a foreign key to a module table in their DefaultValue field. The merge tool ignores the attribute for any formats other than the Key Format Types. Items not listed in the ModuleSubstitution table are excluded from the following check.

The merge tool does not merge the row referenced by the DefaultValue column into the target database if the following conditions are satisfied after completing all configuration options.

Every row in the ModuleConfiguration table with the same DefaultValue has the msmConfigurationItemsKeyNoOrphan set.

No rows use the DefaultValue because the authoring tool declined to provide a value.

The merge tool merges the row if any of the following conditions are satisfied.

The merge tool finds any row that does not have msmConfigItemsKeyNoOrphan set.

If the merge tool finds any row using DefaultValue because the authoring tool declined to provide a value.
msmConfigItemNonNullable | 2 | 0x00000002 | When this attribute is set, NULL is not a valid response for this item. This attribute has no effect for Integer Format Types or Bitfield Format Types.

DisplayName
This column provides a short description of this item that the authoring tool may use in the user interface. This column may not be localized. Set this column to NULL to have the module is request that the authoring tool not expose this property in the UI. The tool may disregard the value in this field.
Description
This column provides a description of this item that the authoring tool may use in UI elements. This string may be localized by the module's language transform. This column may be NULL.
HelpLocation
This column provides either the name of a help file (without the .chm extension) or a semicolon delimited list of help namespaces. This column can be NULL if no help is available. This column can be NULL only if the HelpKeyword column is NULL.
HelpKeyword
This column provides a keyword into the help file or namespace from the HelpLocation column. The interpretation of this keyword depends on the the HelpLocation column. This column may be NULL.

Remarks

The ModuleConfiguration table is used by Configurable Merge Modules. MergeMod.dll version 1.5 or later is required to create a configurable merge module.

To ensure compatibility with older versions of MergeMod.dll, the ModuleConfiguration table and ModuleSubstitution table should be added to the ModuleIgnoreTable table of every module.


Merge Module Summary Information Stream Reference

[This is preliminary documentation and subject to change.]

The following table describes the merge module's summary information stream. See also Summary Information Stream.

Property name | Property ID | PID | Type | Description
Codepage | PID_CODEPAGE | 1 | VT_I2 | Identifies the code page used to display the Summary Information.
Title | PID_TITLE | 2 | VT_LPSTR | "merge module"
Subject | PID_SUBJECT | 3 | VT_LPSTR | ProductName property
Author | PID_AUTHOR | 4 | VT_LPSTR | Manufacturer property
Keywords | PID_KEYWORDS | 5 | VT_LPSTR | "MergeModule, MSI, database"
Comments | PID_COMMENTS | 6 | VT_LPSTR | Description of the merge module and its components.
Template | PID_TEMPLATE | 7 | VT_LPSTR | Platform and language versions supported by database. Specifying more than one language results in a multi-language merge. See Template for syntax.
Last Saved By | PID_LASTAUTHOR | 8 | VT_LPSTR | Specifies the platform and language of the patched database using the same syntax as the Template Summary property.
Revision Number | PID_REVNUMBER | 9 | VT_LPSTR | Unmodified merge module GUID (such as with curly braces and dashes)
Last Printed | PID_LASTPRINTED | 11 | VT_FILETIME | NULL
Create Time/Date | PID_CREATE_DTM | 12 | VT_FILETIME | Time and date when the installer database was created.
Last Saved Time/Date | PID_LASTSAVE_DTM | 13 | VT_FILETIME | Initially NULL. Each time a user changes an installation database the value is updated to the current system time/date at the time the merge database was saved.
Page Count | PID_PAGECOUNT | 14 | VT_I4 | Minimum required installer version. Stored as an integer in the form: Major * 100 + minor.
Word Count | PID_WORDCOUNT | 15 | VT_I4 | "0" Note that merge module files are always inside an embedded cabinet file regardless of the value of this property.
Character Count | PID_CHARCOUNT | 16 | VT_I4 | NULL
Creating Application | PID_APPNAME | 18 | VT_LPSTR | Application used to create the installer database. In general the value is the name of the software used to author this merge module.
Security | PID_SECURITY | 19 | VT_I4 | "2"


Merge Module Automation

[This is preliminary documentation and subject to change.]

MergeMod.dll provides a COM object that implements merge operations and source image generation for merge modules. The main object implements interfaces for C/C++ programs and automation clients, including Visual Basic and VBScript.

The preferred method for installing MergeMod.dll is by using the Microsoft Windows Installer. The Component ID for the component containing the MergeMod.dllCOM interface is {FD153241-37EC-11D2-8892-00A0C981B015}. The same binary can be used on all Windows systems and the DLL will self-register via regsvr32 on older systems.

Note that MergeMod.dll requires that the Msvcrt.dll be installed on the system.

Note that MergeMod.dll version 1.5 is required to create Configurable Merge Modules. MergeMod.dll version 1.5 provides extended functionality at build time via the IMsmMerge2 Interface. This CLSID supports all the existing functionality of the IMsmMerge Interface provided by MergeMod.dll version 1.0. The default interface on the Merge object of MergeMod.dll version 1.5 is the IMsmMerge2 interface instead of the IMsmMerge interface.

Object Model for MergeMod.dll Version 1.0

Object Model for MergeMod.dll Version 1.5


Object Model for MergeMod.dll Version 1.0

[This is preliminary documentation and subject to change.]

The object model for MergeMod.dll is organized as follows:

The Merge object is the primary object of the model. The GetFiles object is a secondary object. Dependencies are collections of Dependency objects. Errors are collections of Error objects.


Object Model for MergeMod.dll Version 1.5

[This is preliminary documentation and subject to change.]

The object model for MergeMod.dll version 1.5 is organized as follows.

The Merge object is the primary object of the model. The GetFiles object is a secondary object. Dependencies are collections of Dependency objects. Errors are collections of Error objects. ConfigurableItems are collections of ConfigurableItem object.


Merge Object

[This is preliminary documentation and subject to change.]

The Merge object provides access to other top-level objects. A Merge object must be created before loading the automation support required by COM to access the functions in MergeMod.dll.

MergeMod.dll provides access to the extended functionality at build time via a second version of the existing CLSID. This CLSID supports existing functionality available via the IMsmMerge interface, but the default interface on the object (and the associated dual interface) is the IMsmMerge2 interface instead of the IMsmMerge interface.


IMsmMerge Interface

[This is preliminary documentation and subject to change.]

The IMsmMerge interface and the IMsmMerge2 interface provide interfaces to the Merge object. The Merge object provides access to other top-level objects. A Merge object must be created before loading the automation support required by COM to access the functions in MergeMod.dll.

Interface ID

Constant | Value
IID_ImsmMerge | {0ADDA82E-2C26-11D2-AD65-00A0C9AF11A6}

Properties

Property | Description
Dependencies | Returns a collection of all unsatisfied dependencies in the database.
Errors | Returns a collection of all errors from the most recent merge operation.

Methods

Method | Description
OpenDatabase | Opens a database to use as the merge target.
OpenModule | Opens a merge module for use as the merge source.
CloseDatabase method | Closes the current database.
CloseModule | Closes the current module
OpenLog | Opens a log file.
CloseLog | Closes the current log file.
Log | Logs a string to the current log file.
Merge | Merges the current module into the current database.
Connect | Connects the components in a module to the specified feature.
ExtractCAB | Extracts the embedded CAB of a Merge Module to a disk file.
ExtractFiles | Creates a source image of the Merge Module beneath the specified path.

C++ Language

interface IMsmMerge : IDispatch


IMsmMerge2 Interface

[This is preliminary documentation and subject to change.]

The IMsmMerge Interface and the IMsmMerge2 interface provide interfaces to the Merge object.The IMsmMerge2 interface provides a way for the client merge tool to utilize the new configurable-module functionality. MergeMod.dll provides access to the extended functionality at build time through a second version of the existing CLSID. This CLSID supports existing functionality available through the IMsmMerge interface, but the default interface on the object (and the associated dual interface) is the IMsmMerge2 interface instead of the IMsmMerge interface.

Requesting this interface does not commit the tool to using the new functionality. The interface supports both the standard and the "Ex" versions of the appropriate interface calls.

The Merge object provides access to other top-level objects. A Merge object must be created before loading the automation support required by COM to access the functions in MergeMod.dll.

Interface ID

Constant | Value
IID_ImsmMerge2 | {351A72AB-21CB-47ab-B7AA-C4D7B02EA305}

Properties

Property | Description
Dependencies | Returns a collection of all unsatisfied dependencies in the database.
Errors | Returns a collection of all errors from the most recent merge operation.
ConfigurableItems | Returns a collection of configurable items in the database. Available in Windows Installer version 1.5 or later.

Methods

Method | Description
OpenDatabase | Opens a database to use as the merge target.
OpenModule | Opens a merge module for use as the merge source.
CloseDatabase | Closes the current database.
CloseModule | Closes the current module
OpenLog | Opens a log file.
CloseLog | Closes the current log file.
Log | Logs a string to the current log file.
Merge | Merges the current module into the current database.
Connect | Connects the components in a module to the specified feature.
ExtractCAB | Extracts the embedded CAB of a Merge Module to a disk file.
ExtractFiles | Creates a source image of the Merge Module beneath the specified path.
MergeEx | Merges the current module into the current database. Available in Windows Installer version 1.5 or later.
ExtractFilesEx | Creates a source image of the Merge Module beneath the specified path. Available in Windows Installer version 1.5 or later.
CreateSourceImage | Extracts files from a module to a source image on disk after a merge, with configuration changes. Available in Windows Installer version 1.5 or later

C++ Language

interface IMsmMerge2 : IDispatch


Dependencies Property (Merge Object)

[This is preliminary documentation and subject to change.]

The read-only Dependencies property returns a collection of Dependency objects that enumerates a set of unsatisfied dependencies for the current database.

Syntax

object.Dependencies

Parameters

object
Merge object

Remarks

There does not need to be a module open to retrieve dependency information.

C++

See get_Dependencies Function.


get_Dependencies Function

[This is preliminary documentation and subject to change.]

The get_Dependencies function implements the Dependencies property (Merge object) of the Merge object.

IMsmMerge::Dependencies All Mergemod.dll versions.

IMsmMerge2::Dependencies Mergemod.dll version 1.5 or later.

HRESULT get_Dependencies(
  IMsmDependencies** Dependencies  //[out, retval]
);

Parameters

Dependencies
Pointer to a memory location to be filled with a pointer to an IMsmDependencies interface which provides access to a collection of unsatisfied dependencies for the current database. If there is an error, the memory location pointed to by Dependencies will be set to NULL.

Return Values

Value | Meaning
E_INVALIDARG | The Dependencies pointer is NULL
E_FAIL | There was no database open.
E_UNEXPECTED | Unable to verify dependencies due to internal error.
E_OUTOFMEMORY | The system ran out of memory.
S_OK | The function succeeded.

Remarks

A module does not need to be open to retrieve dependency information. The client is responsible for releasing the interface returned by this function.

See Also

Merge Module Automation


Errors Property

[This is preliminary documentation and subject to change.]

The read-only Errors property returns a collection of Error objects that is the current set of errors.

Syntax

object.Errors

Parameters

object
Merge object

Remarks

The retrieval is non-destructive. Multiple instances of the error collection may be retrieved by repeatedly calling this method.

C++

See get_Errors Function.


get_Errors Function

[This is preliminary documentation and subject to change.]

The get_Errors function implements the Errors property of the Merge object. This function retrieves the current collection of errors.

IMsmMerge::Errors All Mergemod.dll versions.

IMsmMerge2::Errors Mergemod.dll version 1.5 or later.

HRESULT get_Errors(
  IMsmErrors** Errors
);

Parameters

Errors
[out] Pointer to a memory location containing another pointer to an IMsmErrors interface.

Return Values

Value | Meaning
E_INVALIDARG | The Errors pointer is NULL
E_OUTOFMEMORY | The system ran out of memory.
S_OK | The function succeeded.

Remarks

The retrieval is non-destructive, meaning that several instances of the error collection may be retrieved by repeatedly calling this method.

If there is an error, the memory location pointed to by Errors is set to NULL.

The client is responsible for releasing the interface returned by this function.

See Also

Merge Module Automation


ConfigurableItems Property

[This is preliminary documentation and subject to change.]

The read-only ConfigurableItems property returns a collection ConfigurableItem objects, each of which represents a single row from the ModuleConfiguration table. Semantically, each interface in the enumerator represents an item that can be configured by the module consumer. The collection is a read-only collection and implements the standard read-only collection interfaces of Item(), Count() and _NewEnum(). The IEnumMsmConfigItems enumerator implements Next(), Skip(), Reset(), and Clone() with the standard semantics.

Syntax

object.ConfigurableItems

Parameters

object
Merge object

C++

See get_ConfigurableItems function.


get_ConfigurableItems Function

[This is preliminary documentation and subject to change.]

The get_ConfigurableItems function implements the ConfigurableItems property of the Merge object. This function retrieves the current collection of configurable items.

IMsmMerge2::ConfigurableItems Mergemod.dll version 1.5 or later.

HRESULT get_ConfigurableItems(
  IMsmConfigurableItems** ConfigurableItems
);

Parameters

ConfigurableItems
[out] Pointer to a memory location containing another pointer to an IMsmConfigurableItems interface.

Return Values

Value | Meaning
E_INVALIDARG | The ConfigurableItems pointer is NULL
E_OUTOFMEMORY | The system ran out of memory.
S_OK | The function succeeded.

See Also

Merge Module Automation


OpenDatabase Method (Merge Object)

[This is preliminary documentation and subject to change.]

The OpenDatabase method opens a Windows Installer installation database, located at a specified path, that is to be merged with a module.

Syntax

object.OpenDatabase(Path)

Parameters

object
Merge object
Path
Path to the database being opened.

C++

See OpenDatabase function.


OpenDatabase Function

[This is preliminary documentation and subject to change.]

The OpenDatabase function implements the OpenDatabase Method of the Merge object. This function opens a Windows Installer installation database, located at a specified path, that is to be merged with a module.

IMsmMerge::OpenDatabase All Mergemod.dll versions.

IMsmMerge2::OpenDatabase Mergemod.dll version 1.5 and later.

HRESULT OpenDatabase(
  const BSTR Path
);

Parameters

Path
Path to the database being opened.

Return Values

Value | Meaning
E_FAIL | There was an error opening the database.
S_OK | The function succeeded.

See Also

Merge Module Automation


OpenModule Method

[This is preliminary documentation and subject to change.]

The OpenModule method opens a Windows Installer merge module in read-only mode. A module must be opened before it can be merged with an installation database.

Syntax

object.OpenModule(FileName, Language)

Parameters

object
Merge object
FileName
Fully qualified file name pointing to a merge module.
Language
A valid language identifier (LANGID).

Remarks

This function opens the merge module in read-only mode and excludes other programs from writing to the merge module until the CloseModule method is called.

The installer attempts to open the module in the language specified by Language, or a more general language. For example, if Language is specified as 1033, a module with a default language of 1033, 9, or 0 can be opened in its default language. A Language value of 9 opens modules with a default language of 9 or 0. If the default language of the module does not meet the specified requirements, an attempt is made to transform the module to the requested language. If that fails, the module is transformed to increasingly general languages, all the way to language neutral. If none of the transforms succeed, the module fails to open. In this case, an error is added to the error list of type msmErrorLanguageUnsupported. If there is an error transforming the module to the desired language, an error is added to the error list of type msmErrorLanguageFailed. For details, see the Type property of the Error object. Opening a merge module clears any errors that have not already been retrieved.

C++

See OpenModule function.


OpenModule Function

[This is preliminary documentation and subject to change.]

The OpenModule function implements the OpenModule method of the Merge object. This function opens a Windows Installer merge module in read-only mode. A module must be opened before it can be merged with an installation database.

IMsmMerge::OpenModule All Mergemod.dll versions.

IMsmMerge2::OpenModule Mergemod.dll version 1.5 and later.

HRESULT OpenModule(
  BSTR FileName,
  short Language
);

Parameters

FileName
[in] Fully qualified filename pointing to a merge module. A LPCWSTR may be used in place of a BSTR.
Language
[in] A language identifier (LANGID).

Return Values

Value | Meaning
ERROR_TOO_MANY_OPEN_FILES as HRESULT | There is already a module open. Closes the current module first.
E_ABORT | The file specified is an Windows Installer database, but is not a Merge Module (missing ModuleSignature table)
ERROR_OPEN_FAILED as HRESULT | The file could not be opened as an Windows Installer database.
ERROR_INSTALL_TRANSFORM_FAILURE as HRESULT | The language is supported by the module, but there was an error applying the transform.
ERROR_INSTALL_LANGUAGE_UNSUPPORTED as HRESULT | The language is not supported by the module.
S_OK | The function succeeded

Remarks

This function opens the merge module in read-only mode (MSIDBOPEN_READONLY), and excludes other programs from writing to the merge module until the CloseModule function is called. A merge module must be opened before it can be merged.

The installer attempts to open the module in the language specified by Language or in any more general language. For example, if 1033 is specified by the Language value, a module with a default language of 1033, 9, or 0 will be opened in its default language. A Language value of 9 will open modules with a default language of 9 or 0. If the default language of the module does not meet the specified requirements, an attempt is made to transform the module into the requested language. If that fails, the installer attempts to transform the module into increasingly general languages, all the way to language neutral. If none of the transforms succeed, the module fails to open. In this case, an error is added to the error list of type msmErrorLanguageUnsupported and the function returns ERROR_INSTALL_LANGUAGE_UNSUPPORTED as HRESULT.

If there is an error transforming the module to the desired language, an error is created of type msmErrorLanguageFailed and the function returns ERROR_INSTALL_TRANSFORM_FAILURE as HRESULT.

For more information, see the Type property of the Error object.

Opening a merge module clears any errors that have not already been retrieved.

See Also

Merge Module Automation


CloseDatabase Method

[This is preliminary documentation and subject to change.]

The CloseDatabase method closes the currently open Windows Installer database.

Syntax

object.CloseDatabase(bCommit)

Parameters

object
Merge object
bCommit
TRUE if changes should be saved, FALSE otherwise.

Remarks

Closing a database clears all dependency information but does not affect any errors that have not been retrieved.

C++

See CloseDatabase function.


CloseDatabase Function

[This is preliminary documentation and subject to change.]

The CloseDatabase function implements the CloseDatabase method of the Merge object. The function closes the currently open Windows Installer database.

IMsmMerge::CloseDatabase All Mergemod.dll versions.

IMsmMerge2::CloseDatabase Mergemod.dll version 1.5 or later.

HRESULT CloseDatabase(
  VARIANT_BOOL bCommit
);

Parameters

bCommit
TRUE if changes should be saved, FALSE otherwise.

Return Values

Value | Meaning
E_FAIL | There was an error closing the database. The state of the IMsmMerge or IMsmMerge2 interface is now in an undefined state.
STG_E_CANTSAVE as HRESULT | Unable to save database. This error is not generated if bCommit is FALSE.
S_FALSE | No database was open.
S_OK | The function succeeded.

Remarks

This function closes the currently open database. Closing a database clears all dependency information but does not affect any errors that have not been retrieved.

See Also

Merge Module Automation


CloseModule Method

[This is preliminary documentation and subject to change.]

The CloseModule method closes the currently open Windows Installer merge module.

Syntax

object.CloseModule

Parameters

object
Merge object

Remarks

Closing a merge module will not affect any errors that have not been retrieved.

C++

See CloseModule function.


CloseModule Function

[This is preliminary documentation and subject to change.]

The CloseModule function implements the CloseModule method of the Merge object. This function closes the currently open Windows Installer merge module.

IMsmMerge::CloseModule All Mergemod.dll versions.

IMsmMerge2::CloseModule Mergemod.dll version 1.5 or later.

HRESULT CloseModule();

Parameters

None

Return Values

Value | Meaning
E_FAIL | There was an error closing the module. The state of the IMsmMerge or IMsmMerge2 interface is now undefined.
S_FALSE | No module was open.
S_OK | The function succeeded.

Remarks

Closing a merge module does not affect any errors that have not been retrieved.

See Also

Merge Module Automation


OpenLog Method

[This is preliminary documentation and subject to change.]

The OpenLog method opens a log file that receives progress and error messages. If the log file already exists, the installer appends new messages. If the log file does not exist, the installer creates a log file.

Syntax

object.OpenLog(Filename)

Parameters

object
Merge object
Filename
Fully qualified filename pointing to a file to open or create.

Remarks

Clients may send their own messages to this log file via the Log method.

C++

See OpenLog function.


OpenLog Function

[This is preliminary documentation and subject to change.]

The OpenLog function implements the OpenLog method of the Merge object. This function opens a log file that receives progress and error messages. If the log file already exists, the installer appends new messages. If the log file does not exist, the installer creates a log file.

IMsmMerge::OpenLog All Mergemod.dll versions.

IMsmMerge2::OpenLog Mergemod.dll version 1.5 or later.

HRESULT OpenLog(
BSTR FileName
);

Parameters

FileName
[in] Fully qualified filename pointing to a file to open or create. A LPCWSTR may be used in place of a BSTR.

Return Values

Value | Meaning
ERROR_TOO_MANY_OPEN_FILES as HRESULT | There is already a log file open.
ERROR_OPEN_FAILED as HRESULT | The file could not be opened or created.
S_OK | The function succeeded.

Remarks

This function opens a log file to receive progress and error messages. If the log file already exists, new messages get appended to the log. If the log file does not exist it is created.

Clients may send their own messages to this log file using the Log Function.

See Also

Merge Module Automation


CloseLog Method

[This is preliminary documentation and subject to change.]

The CloseLog method closes the current log file.

Syntax

object.CloseLog

Parameters

object
Merge object

C++

See CloseLog function.


CloseLog Function

[This is preliminary documentation and subject to change.]

The CloseLog function implements the CloseLog method of the Merge object. This function closes the current log.

IMsmMerge::CloseLog All Mergemod.dll versions.

IMsmMerge2::CloseLog Mergemod.dll version 1.5 or later.

HRESULT CloseLog();

Parameters

This function has no parameters.

Return Values

Value | Meaning
E_FAIL | There was an error closing the log file.
S_FALSE | No log file was open.
S_OK | The function succeeded.

See Also

Merge Module Automation


Log Method

[This is preliminary documentation and subject to change.]

The Log method writes a text string to the currently open log file.

Syntax

object.Log(Message)

Parameters

object
Merge object
Message
The text string to write to the log file.

C++

See Log function.


Log Function

[This is preliminary documentation and subject to change.]

The Log function implements the Log method of the Merge object. This function writes a text string to the currently open log file.

IMsmMerge::Log All Mergemod.dll versions.

IMsmMerge2::Log Mergemod.dll version 1.5 or later.

HRESULT Log(
  BSTR Message
);

Parameters

Message
The text string to display. A LPCWSTR may be used instead of a BSTR.

Return Values

Value | Meaning
E_FAIL | There was an error writing to the log file.
E_INVALIDARG | The argument is invalid.
S_FALSE | No log file is open.
S_OK | The function succeeded.

See Also

Merge Module Automation


Merge Method (Merge Object)

[This is preliminary documentation and subject to change.]

The Merge method executes a merge of the current database and current module. The merge attaches the components in the module to the feature identified by Feature. The root of the module's directory tree is redirected to the location given by RedirectDir.

The Merge method can only be called once to merge a particular combination of .msi and .msm files.

Syntax

object.Merge(Feature, RedirectDir)

Parameters

object
Merge object
Feature
The name of a feature in the database.
RedirectDir
The key of an entry in the Directory table of the database. This parameter may be NULL or an empty string.

Remarks

Once the merge is complete, components in the module are attached to the feature identified by Feature. This feature is not created and must be an existing feature. The Merge method substitutes the feature reference for all occurrences of the null GUID in the module database. For more information, see Referencing Features in Merge Modules.

The module may be attached to additional features using the Connect method.

Changes made to the database are saved if and only if the CloseDatabase method is called with bCommit set to TRUE.

If any merge conflicts occur, including exclusions, they are placed in the error enumerator for later retrieval, but does not cause the merge to fail. Errors may be retrieved through the Errors property. Errors and informational messages are posted to the current log file.

C++

See Merge function.


Merge Function

[This is preliminary documentation and subject to change.]

The Merge function implements the Merge method of the of the Merge object. This function executes a merge of the current database and current module. The merge attaches the components in the module to the feature identified by Feature. The root of the module's directory tree is redirected to the location given by RedirectDir.

IMsmMerge::Merge All Mergemod.dll versions.

IMsmMerge2::Merge Mergemod.dll version 1.5 or later.

HRESULT Merge(
  const BSTR Feature,
  const BSTR RedirectDir
);

Parameters

Feature
[in] The name of a feature in the database. A LPCWSTR may be used in place of a BSTR.
RedirectDir
[in] The key of an entry in the Directory table of the database. A LPCWSTR may be used in place of a BSTR. This parameter may be NULL or an empty string.

Return Values

Value | Meaning
E_OUTOFMEMORY | The system ran out of memory and could not complete the operation.
E_INVALIDARG | One of the arguments is invalid.
E_FAIL | The merge failed catastrophically. This indicates an operational error, and is not the normal error return for a failed merge.
S_FALSE | The function succeeded, but there were errors and the merge itself may not be valid.
S_OK | The function succeeded.

Remarks

This function executes a merge of the current database and current module. The root of the module's directory tree is redirected to the location given by RedirectDir. If any merge conflicts occur, including exclusions, they are placed in the error enumerator for later retrieval, but does not cause the merge to fail. Errors may be retrieved using get_Errors function. Errors and informational messages are posted to the current log file.

Once the merge is complete, components in the module are attached to the feature identified by Feature. This feature must already exist and is not created. The module may be attached to additional features using Connect function.

Changes made to the database are not saved to disk unless CloseDatabase function is called with bCommit set to TRUE.

See Also

Merge Module Automation


Connect Method

[This is preliminary documentation and subject to change.]

The Connect method connects a module to an additional feature. The module must have already been merged into the database or will be merged into the database. The feature must exist before calling this function.

Changes made to the database are not saved to disk unless the CloseDatabase method is called with bCommit set to TRUE.

Syntax

object.Connect(Feature)

Parameters

object
Merge object
Feature
The name of a feature already existing in the database.

Remarks

Errors may be retrieved through the Errors property. Errors and informational messages are posted to the current log file.

C++

See Connect function.


Connect Function

[This is preliminary documentation and subject to change.]

The Connect function implements the Connect method of the Merge object. This function connects a module that has been, or will be, merged into the database to an additional feature.

IMsmMerge::Connect All Mergemod.dll versions.

IMsmMerge2::Connect Mergemod.dll version 1.5 or later.

HRESULT Connect(
  BSTR Feature
);

Parameters

Feature
[in] The name of a feature in the database. A LPCWSTR may be used in place of a BSTR.

Return Values

Value | Meaning
E_INVALIDARG | One of the arguments is invalid.
E_FAIL | The connect failed.
S_OK | The function succeeded.

Remarks

The feature must exist before this function is called. Errors may be retrieved using get_Errors function. Errors and informational messages are posted to the current log file.

Changes made to the database are not be saved to disk unless CloseDatabase function is called with bCommit set to TRUE.

See Merge Module Automation.


ExtractCAB Method

[This is preliminary documentation and subject to change.]

The ExtractCAB method extracts the embedded .cab file from a module and saves it as the specified file. The installer creates this file if it does not already exist and overwritten if it does exist.

Syntax

object.ExtractCAB(FileName)

Parameters

object
Merge object
FileName
The fully qualified destination file.

C++

See ExtractCAB function.


ExtractCAB Function

[This is preliminary documentation and subject to change.]

The ExtractCAB function implements the ExtractCAB method of the Merge object. This function extracts the embedded .cab file from a module and saves it as the specified file. The installer creates this file if it does not already exist and overwrites the file if it does exist.

IMsmMerge::ExtractCAB All Mergemod.dll versions.

IMsmMerge2::ExtractCAB Mergemod.dll version 1.5 or later.

HRESULT ExtractCAB(
  BSTR FileName
);

Parameters

FileName
[in] The fully qualified destination file. A LPCWSTR may be used in place of a BSTR.

Return Values

Value | Meaning
E_INVALIDARG | One of the arguments is invalid.
ERROR_OPEN_FAILED as HRESULT | Could not create the output file.
ERROR_WRITE_FAULT as HRESULT | Could not write data to the output file.
E_FAIL | Unable to access embedded .cab file.
S_FALSE | No embedded .cab file was found.
S_OK | The function succeeded.

Remarks

See Merge Module Automation.


ExtractFiles Method

[This is preliminary documentation and subject to change.]

The ExtractFiles method extracts the embedded .cab file from a module and then writes those files to the destination directory.

Syntax

object.ExtractFiles(Path)

Parameters

object
Merge object
Path
The fully qualified destination directory.

Remarks

Any files in the destination directory with the same name are overwritten. The path is created if it does not already exist.

C++

See ExtractFiles function.


ExtractFiles Function

[This is preliminary documentation and subject to change.]

The ExtractFiles function implements the ExtractFiles method of the Merge object. This function extracts the embedded .cab file from a module and then writes those files to the destination directory.

IMsmMerge::ExtractFiles All Mergemod.dll versions.

IMsmMerge2::ExtractFiles Mergemod.dll version 1.5 or later.

HRESULT ExtractFiles(
  BSTR Path
);

Parameters

Path
[in] The fully qualified destination directory. A LPCWSTR may be used in place of a BSTR.

Return Values

Value | Meaning
ERROR_CANNOT_MAKE as HRESULT | Could not create the output path.
ERROR_OPEN_FAILED as HRESULT | Could not create the output file.
ERROR_WRITE_FAULT as HRESULT | Could not write data to the output file.
E_FAIL | Unable to access embedded .cab file, or create temporary file.
S_FALSE | No embedded .cab file was found.
S_OK | The function succeeded.

Remarks

Any files in the destination directory with the same name are overwritten. The path is created if it does not already exist.

See Merge Module Automation.


MergeEx Method

[This is preliminary documentation and subject to change.]

The MergeEx method is equivalent to the Merge function, except that it takes an extra argument. The pConfiguration argument is an interface implemented by the client. The argument may be NULL. The presence of this argument indicates that the client is capable of supporting the configuration functionality, but does not obligate the client to provide configuration data for any specific configurable item.

The Merge method executes a merge of the current database and current module. The merge attaches the components in the module to the feature identified by Feature. The root of the module's directory tree is redirected to the location given by RedirectDir.

Syntax

object.MergeEx(Feature, RedirectDir, pConfiguration)

Parameters

object
Merge object
Feature
The name of a feature in the database.
RedirectDir
The key of an entry in the Directory table of the database. This parameter may be NULL or an empty string.
pConfiguration
The pConfiguration argument is an interface implemented by the client. The argument may be NULL. The presence of this argument indicates that the client is capable of supporting the configuration functionality, but does not obligate the client to provide configuration data for any specific configurable item.

Remarks

Once the merge is complete, components in the module are attached to the feature identified by Feature. This feature is not created and must be an existing feature. The module may be attached to additional features using the Connect method.

Changes made to the database are saved if and only if the CloseDatabase method is called with bCommit set to TRUE.

If any merge conflicts occur, including exclusions, they are placed in the error enumerator for later retrieval, but does not cause the merge to fail. Errors may be retrieved through the Errors property. Errors and informational messages are posted to the current log file.

C++

See MergeEx function.


MergeEx Function

[This is preliminary documentation and subject to change.]

The MergeEx function implements the MergeEx method of the of the Merge object. This function executes a merge of the current database and current module. The merge attaches the components in the module to the feature identified by Feature. The root of the module's directory tree is redirected to the location given by RedirectDir

IMsmMerge2::MergeEx Mergemod.dll version 1.5 or later.

HRESULT MergeEx(
  const BSTR Feature,
  const BSTR RedirectDir
  IMsmConfigureModule* pConfiguration
);

Parameters

Feature
[in] The name of a feature in the database. A LPCWSTR may be used in place of a BSTR.
RedirectDir
[in] The key of an entry in the Directory table of the database. A LPCWSTR may be used in place of a BSTR. This parameter may be NULL or an empty string.
pConfiguration
[in] The pConfiguration argument is an interface implemented by the client. The argument may be NULL. The presence of this argument indicates that the client tool is capable of modifying configurable merge modules. The presence of this argument does not require the client to provide configuration data for any specific configurable item.

Return Values

Value | Meaning
E_OUTOFMEMORY | There system ran out of memory and could not complete the operation.
E_INVALIDARG | One of the arguments is invalid.
E_FAIL | The merge failed catastrophically. This indicates an operational error, and is not the normal error return for a failed merge.
S_FALSE | The function succeeded, but there were errors and the merge itself may not be valid.
S_OK | The function succeeded.

Remarks

This function executes a merge of the current database and current module. The root of the module's directory tree is redirected to the location given by RedirectDir. If any merge conflicts occur, including exclusions, they are placed in the error enumerator for later retrieval, but does not cause the merge to fail. Errors may be retrieved using get_Errors function. Errors and informational messages will be posted to the current log file.

Once the merge is complete, components in the module are attached to the feature identified by Feature. This feature must already exist and is not created. The module may be attached to additional features using Connect function.

Changes made to the database will not be saved to disk unless CloseDatabase function is called with bCommit set to TRUE.

See Also

Merge Module Automation


ExtractFilesEx Method

[This is preliminary documentation and subject to change.]

The ExtractFilesEx method extracts the embedded .cab file from a module and then writes those files to the destination directory.

Syntax

object.ExtractFilesEx(Path,fLongFileNames,pFilePaths)

Parameters

object
Merge object
Path
The fully qualified destination directory.
fLongFileNames
Set to specify using long file names for path segments and final file names.
pFilePaths
This is a list of fully-qualified paths for the files that were successfully extracted. Null if no files were successfully extracted.

Remarks

Any files in the destination directory with the same name are overwritten. The path is created if it does not already exist.

C++

See ExtractFilesEx function.


ExtractFilesEx Function

[This is preliminary documentation and subject to change.]

The ExtractFilesEx function implements the ExtractFilesEx method of the Merge object. This function extracts the embedded .cab file from a module and then writes those files to the destination directory.

IMsmMerge2::ExtractFilesEx Mergemod.dll version 1.5 or later.

HRESULT ExtractFilesEx(
  BSTR Path
  VARIANT_BOOL fLongFileNames
  IMsmStrings* pFilePaths
);

Parameters

Path
[in] The fully qualified destination directory. A LPCWSTR may be used in place of a BSTR.
fLongFileNames
[in] Set to specify using long file names for path segments and final file names.
pFilePaths
[out] This is a list of fully-qualified paths for the files that were successfully extracted. Null if no files were successfully extracted.

Return Values

Value | Meaning
ERROR_CANNOT_MAKE as HRESULT | Could not create the output path.
ERROR_OPEN_FAILED as HRESULT | Could not create the output file.
ERROR_WRITE_FAULT as HRESULT | Could not write data to the output file.
E_FAIL | Unable to access embedded .cab file, or create temporary file.
S_FALSE | No embedded .cab file was found.
S_OK | The function succeeded.

Remarks

Any files in the destination directory with the same name are overwritten. The path is created if it does not already exist.

See Merge Module Automation.


CreateSourceImage Method

[This is preliminary documentation and subject to change.]

The CreateSourceImage method allows the client to extract the files from a module to a source image on disk after a merge, taking into account changes to the module that might have been made during module configuration. The list of files to be extracted is taken from the file table of the module during the merge process. The list of files consists of every file successfully copied from the file table of the module to the target database. File table entries that were not copied due to primary key conflicts with existing rows in the database are not a part of this list. At image creation time, the directory for each of these files comes from the open (post-merge) database. The path specified in the Path parameter is the root of the source image for the install. fLongFileNames determines whether or not long file names are used for both path segments and final file names. The function fails if no database is open, no module is open, or no merge has been performed.

Syntax

object.CreateSourceImage(Path,fLongFileNames,pFilePaths)

Parameters

object
Merge object
Path
The path of the root of the source image for the install.
fLongFileNames
fLongFileNames determines whether or not long file names are used for both path segments and final file names.
pFilePaths
This is a list of fully-qualified paths for the files that were successfully extracted. Null if no files were successfully extracted.

Remarks

Any files in the destination directory with the same name are overwritten. The path is created if it does not already exist.

C++

See CreateSourceImage function.


CreateSourceImage Function

[This is preliminary documentation and subject to change.]

The CreateSourceImage function implements the CreateSourceImage method of the Merge object.

IMsmMerge2::CreateSourceImage Mergemod.dll version 1.5 or later.

HRESULT CreateSourceImage(
  BSTR Path
  VARIANT_BOOL fLongFileNames
  IMsmStrings* pFilePaths
);

Parameters

Path
[in] The path of the root of the source image for the install.
fLongFileNames
[in] fLongFileNames determines whether or not long file names are used for both path segments and final file names.
pFilePaths
[out] This is a list of fully-qualified paths for the files that were successfully extracted. Null if no files were successfully extracted.

Remarks

See Merge Module Automation.


Dependency Object

[This is preliminary documentation and subject to change.]

The Dependency object returns a module that the current module is dependent upon and which has not yet been merged into the current installation database.

Interface ID

Constant | Value
IID_IMsmDependency | {0ADDA82D-2C26-11D2-AD65-00A0C9AF11A6}

Properties

Property | Description
Module | Return the module ID of the required module.
Version | Return the version of the required module.
Language | Return the language of the module.

Methods

None.

C++

interface IMsmDependency : IDispatch


Module Property

[This is preliminary documentation and subject to change.]

The read-only Module property returns the ModuleID of the module required by the current string in the form of a BSTR. The ModuleID is of the same form as used in the ModuleSignature table.

Syntax

object.Module

Parameters

object
Dependency object

C++

See get_Module function.


get_Module Function

[This is preliminary documentation and subject to change.]

The get_Module function implements the Module Property of the Dependency object. This function returns the ModuleID of the module required by the current string in the form of a BSTR. The ModuleID is of the same form as used in the ModuleSignature table.

IMsmDependency::get_Module

HRESULT get_Module(
  BSTR* Module
);

Parameters

Module
[out, retval] A pointer to a location in memory that is filled in with a BSTR value.

Return Values

Value | Meaning
E_INVALIDARG | Module is NULL
S_OK | The function succeeded

Remarks

The client is responsible for freeing the resulting string using SysFreeString().

See Also

Merge Module Automation


Version Property (Dependency Object)

[This is preliminary documentation and subject to change.]

The read-only Version property returns the version of the module required by the current merge.

Syntax

object.Version

Parameters

object
Dependency object

C++

See get_Version function.


get_Version Function

[This is preliminary documentation and subject to change.]

The get_Version function implements the Version Property of the Dependency object. This function returns the version of the required module in the form of a BSTR.

IMsmDependency::get_Version

HRESULT get_Version(
  BSTR* Version
);

Parameters

Version
[out, retval] A pointer to a location in memory that is filled in with a BSTR value.

Return Values

Value | Meaning
E_INVALIDARG | Version is NULL.
S_OK | The function succeeded.

Remarks

The client is responsible for freeing the resulting string using SysFreeString().

See Also

Merge Module Automation


Language Property (Dependency Object)

[This is preliminary documentation and subject to change.]

The read-only Language property returns the LANGID of the required module.

Syntax

object.Language

Parameters

object
Dependency object

C++

See get_Language Function (Dependency Object).


get_Language Function (Dependency Object)

[This is preliminary documentation and subject to change.]

The get_Language function implements the Language property of the Dependency object. This function returns the LANGID of the required module.

IMsmDependency::get_Language

HRESULT get_Language(
  short* Language
);

Parameters

Language
[out, retval] A pointer to a location in memory that is filled with the desired language.

Return Values

Value | Meaning
E_INVALIDARG | Language is NULL.
S_OK | The function succeeded.

See Also

Merge Module Automation


Error Object

[This is preliminary documentation and subject to change.]

The Error object returns the information of a single merge error.

Interface ID

Constant | Value
IID_IMsmError | {0ADDA828-2C26-11D2-AD65-00A0C9AF11A6}

Properties

Property | Description
Type | Return the type of error.
Path | Return the path to the file or directory causing the error. Currently unused.
Language | Return the language of the error.
DatabaseTable | Returns the table name of the table in the database causing the error.
ModuleTable | Returns the table name of the table in the module causing the error.
DatabaseKeys | Returns the primary keys of the row in the database table that caused the error.
ModuleKeys | Returns the primary keys of the row in the module table that caused the error.

Methods

None.

C++

interface IMsmError : IDispatch


Type Property (Error Object)

[This is preliminary documentation and subject to change.]

The read-only Type property returns one of the values of msmErrorType, indicating the type of error represented by this object.

Syntax

object.Type

Parameters

object
Error object

C++

See get_Type Function (Error Object).


get_Type Function (Error Object)

[This is preliminary documentation and subject to change.]

The get_Type function implements the Type property of the Error object. This function returns a msmErrorType value indicating the type of error represented by this object.

IMsmError::get_Type

HRESULT get_Type(
  msmErrorType* ErrorType
);

Parameters

ErrorType
[out, retval] A pointer to a location in memory that is filled with the type of error.
msmErrorType | Value | Description
msmErrorLanguageUnsupported | 1
msmErrorLanguageFailed | 2
msmErrorExclusion | 3
msmErrorTableMerge | 4
msmErrorResequenceMerge | 5
msmErrorFileCreate | 6
msmErrorDirCreate | 7
msmErrorFeatureRequired | 8
msmErrorBadNullSubstitution | 9 | Available with Window Installer version 1.5. Substitution of a Null value into a non-nullable column. This enters msmErrorBadNullSubstitution in the Type property and enters "ModuleSubstitution" and the keys from the ModuleSubstitution table for this row into the ModuleTable property and ModuleKeys property. All other properties of the Error object are set to an empty string or -1.
msmErrorBadSubstitutionType | 10 | Available with Window Installer version 1.5. Substitution of Text Format Type or Integer Format Type into a Binary Type data column. This type of error returns msmErrorBadSubstitutionType in the Type property and enters "ModuleSubstitution" and the keys from the ModuleSubstitution table for this row into the ModuleTable property. All other properties of the Error object are set to an empty string or -1.
msmErrorMissingConfigItem | 11 | Available with Window Installer Version 1.5. A row in the ModuleSubstitution table references a configuration item not defined in the ModuleConfiguration table. This type of error returns msmErrorMissingConfigItem in the Type property and enters "ModuleSubstitution" and the keys from the ModuleSubstitution table for this row into the ModuleTable property. All other properties of the Error object are set to an empty string or -1.
msmErrorBadNullResponse | 12 | Available with Window Installer version 1.5. The authoring tool has returned a Null value for an item marked with the msmConfigItemNonNullable attribute. An error of this type returns msmErrorBadNullResponse in the Type property and enters "ModuleSubstitution" and the keys from the ModuleSubstitution table for for the item into the ModuleTable property. All other properties of the Error object are set to an empty string or -1.
msmErrorDataRequestFailed | 13 | Available with Window Installer version 1.5. The authoring tool returned a failure code (not S_OK or S_FALSE) when asked for data. An error of this type will return msmErrorDataRequestFailed in the Type property and enters "ModuleSubstitution" and the keys from the ModuleSubstitution table for the item into the ModuleTable property. All other properties of the Error object are set to an empty string or -1.

Return Values

Value | Meaning
E_INVALIDARG | ErrorType is Null.
S_OK | The function succeeded.

See Also

Merge Module Automation


Path Property

[This is preliminary documentation and subject to change.]

In Windows Installer versions 1.0 and 1.1 the Path property is always the empty string. Future versions may use this value to return the path to the file or directory that could not be created.

Syntax

object.Path

Parameters

object
Error object
Path
A pointer to a location in memory that is filled in with a BSTR value.

Remarks

This value is only valid for errors of type msmErrorFileCreate or msmErrorDirCreate. You can determine the type of error by calling Type property of the Error object.

C++

See get_Path function.


get_Path Function

[This is preliminary documentation and subject to change.]

The get_Path function implements the Path property of the Error object.

IMsmError::get_Path

HRESULT get_Path(
  BSTR* Path
);

Parameters

Path
[out, retval] A pointer to a location in memory that is filled in with a BSTR value.

Return Values

Value | Meaning
E_INVALIDARG | Path is NULL.
E_OUTOFMEMORY | The system was unable to allocate memory for the string.
S_OK | The function succeeded.

Remarks

The client is responsible for freeing the resulting string using SysFreeString().

In Windows Installer versions 1.0 and 1.1 get_Path always returns the empty string. Future versions of the class may use this function to return the path to the file or directory that could not be created. This value is only valid for errors of type msmErrorFileCreate or msmErrorDirCreate. You can determine the type of error by calling IMsmError::get_Type.

See Also

Merge Module Automation


Language Property (Error Object)

[This is preliminary documentation and subject to change.]

The read-only Language property of the Error object returns the LANGID of the current error.

Syntax

object.Language

Parameters

object
Error object

Remarks

The value of the Language property is -1 unless the error is of type msmErrorLanguageUnsupported or msmErrorLanguageFailed. You can determine the type of error by calling the Type property of the Error object.

C++

See get_Language Function (Error Object).


get_Language Function (Error Object)

[This is preliminary documentation and subject to change.]

The get_Language function implements the Language property of the Error object. This function returns the LANGID of the error.

IMsmError::get_Language

HRESULT get_Language(
  short* Language
);

Parameters

Language
[out, retval] A pointer to a location in memory that is filled with the language value causing this error.

Return Values

Value | Meaning
E_INVALIDARG | Language is NULL.
S_OK | The function succeeded.

Remarks

The function returns -1 unless the error is of type msmErrorLanguageUnsupported or msmErrorLanguageFailed. You can determine the type of error by calling IMsmError::get_Type.

See Also

Merge Module Automation


DatabaseTable Property

[This is preliminary documentation and subject to change.]

The read-only DatabaseTable Property returns the name of the table in the database that caused the error.

Syntax

object.DatabaseTable

Parameters

object
Error object

Remarks

The table name is the empty string unless the error is of type msmErrorTableMerge or msmErrorResequenceMerge. You can determine the type of error by calling Type property of the Error object.

C++

See get_DatabaseTable function.


get_DatabaseTable Function

[This is preliminary documentation and subject to change.]

The get_DatabaseTable function implements the DatabaseTable property of the Error object. The function returns the name of the table in the database that caused the error.

IMsmError::get_DatabaseTable

HRESULT get_DatabaseTable(
  BSTR* Table
);

Parameters

Table
[out, retval] A pointer to a location in memory that is filled in with a BSTR value.

Return Values

Value | Meaning
E_INVALIDARG | Table is NULL.
E_OUTOFMEMORY | The system was unable to allocate memory for the string.
S_OK | The function succeeded.

Remarks

The client is responsible for freeing the resulting string using SysFreeString().

The function returns an empty string unless the error is of type msmErrorTableMerge or msmErrorResequenceMerge. You can determine the type of error by calling IMsmError::get_Type.

See Also

Merge Module Automation


ModuleTable Property

[This is preliminary documentation and subject to change.]

The read-only ModuleTable Property returns the name of the table in the module that caused the error.

Syntax

object.ModuleTable

Parameters

object
Error object

Remarks

The table name is the empty string unless the error is of type msmErrorTableMerge or msmErrorResequenceMerge. You can determine the type of error by calling the Type property of the Error object.

C++

See get_ModuleTable function.


get_ModuleTable Function

[This is preliminary documentation and subject to change.]

The get_ModuleTable function implements the ModuleTable property of the Error object. This function returns the name of the table in the module that caused the error.

IMsmError::get_ModuleTable

HRESULT get_ModuleTable(
  BSTR* Table
);

Parameters

Table
[out, retval] A pointer to a location in memory that is filled in with a BSTR value.

Return Values

Value | Meaning
E_INVALIDARG | Table is NULL.
E_OUTOFMEMORY | The system was unable to allocate memory for the string.
S_OK | The function succeeded.

Remarks

The client is responsible for freeing the resulting string using SysFreeString().

The table name is the empty string unless the error is of type msmErrorTableMerge or msmErrorResequenceMerge. You can determine the type of error by calling IMsmError::Type.

See Also

Merge Module Automation


DatabaseKeys Property

[This is preliminary documentation and subject to change.]

The read-only DatabaseKeys property returns a string collection that contains the primary keys of the database row causing the error. There is one key per entry in the collection.

Syntax

object.DatabaseKeys

Parameters

object
Error object

Remarks

The client is responsible for releasing the string collection when it is no longer needed.

The collection is empty if the error is of type msmErrorLanguageUnsupported or msmErrorLanguageFailed. You can determine the type of error by calling the Type property of the Error object.

C++

See get_DatabaseKeys function.


get_DatabaseKeys Function

[This is preliminary documentation and subject to change.]

The get_DatabaseKeys function implements the DatabaseKeys property. This function returns a pointer to a string collection containing the primary keys of the row in the database causing the error, one key per entry in the collection.

IMsmError::get_DatabaseKeys

HRESULT get_DatabaseKeys(
  IMsmStrings** ErrorKeys
);

Parameters

ErrorKeys
[out, retval] A pointer to a location in memory that is filled with a pointer to a string collection.

Return Values

Value | Meaning
E_INVALIDARG | ErrorKeys is NULL.
S_OK | The function succeeded.

Remarks

The client is responsible for releasing the string collection when it is no longer needed.

The collection is empty if the error is of type msmErrorLanguageUnsupported or msmErrorLanguageFailed. You can determine the type of error using IMsmError::Type.

See Also

Merge Module Automation


ModuleKeys Property

[This is preliminary documentation and subject to change.]

The read-only ModuleKeys property returns a pointer to a string collection containing the primary keys of the row in the module causing the error, one key per entry in the collection.

Syntax

object.ModuleKeys

Parameters

object
Error object

Remarks

The client is responsible for releasing the string collection when it is no longer needed.

The collection is empty if the error is of type msmErrorLanguageUnsupported or msmErrorLanguageFailed. You can determine the type of error by calling the Type property of the Error object.

C++

See get_ModuleKeys function.


get_ModuleKeys Function

[This is preliminary documentation and subject to change.]

The get_ModuleKeys function implements the ModuleKeys property. This function returns a pointer to a string collection containing the primary keys of the row in the module causing the error, one key per entry in the collection.

IMsmError::get_ModuleKeys

HRESULT get_ModuleKeys(
  IMsmStrings** ErrorKeys
);

Parameters

ErrorKeys
[out, retval] A pointer to a location in memory that is filled with a pointer to a string collection.

Return Values

Value | Meaning
E_INVALIDARG | ErrorKeys is NULL.
S_OK | The function succeeded

Remarks

The client is responsible for releasing the string collection when it is no longer needed.

The collection is empty if the error is of type msmErrorLanguageUnsupported or msmErrorLanguageFailed. You can determine the type of error by calling IMsmError::Type.

See Also

Merge Module Automation


GetFiles Object

[This is preliminary documentation and subject to change.]

The GetFiles object retrieves the files needed in a particular language of the module. Requires certain actions be performed via the Merge object before all parts of this interface returns valid results.

Interface ID

Constant | Value
IID_IMsmGetFiles | {7041AE26-2D78-11D2-888A-00A0C981B015}

Properties

Property | Description
ModuleFiles | ModuleFiles property returns all the primary keys of the File table for the currently open module.

Methods

None.

C++

interface IMsmGetFiles : IDispatch


ModuleFiles Property

[This is preliminary documentation and subject to change.]

ModuleFiles Property returns all the primary keys of the File table for the currently open module. The primary keys are returned as a collection of strings. The module must be opened by a call to the OpenModule method of the Merge object before calling ModuleFiles.

Syntax

object.ModuleFiles

Parameters

object
GetFiles object

Remarks

Note that order of the files listed in the collection may not be in the same sequence as listed in the File table.

If the module has no File table, or contains no files in the particular language, ModuleFiles returns an empty collection of strings.

C++

See get_ModuleFiles function.


get_ModuleFiles Function

[This is preliminary documentation and subject to change.]

The get_ModuleFiles function implements the ModuleFiles property of the GetFiles object. This function returns the primary keys in the File table of the currently open module. The primary keys are returned as a collection of strings. The module must be opened by a call to the OpenModule function before calling get_ModuleFiles.

IMsmGetFiles::get_ModuleFiles

HRESULT get_ModuleFiles(
  IMsmStrings* Files
);

Parameters

Files
[retval, out] Collection of IMsmStrings that are the primary keys of the File table for the currently open module.

Return Values

Value | Meaning
E_INVALIDARG | Invalid argument.
S_OK | The function succeeded.
E_FAIL | No module is open.
E_OUTOFMEMORY | Out of memory.
ERROR_FUNCTION_FAILED as HRESULT | The function failed.
ERROR_INVALID_HANDLE as HRESULT | The function failed.

See Also

Merge Module Automation


ConfigurableItem Object

[This is preliminary documentation and subject to change.]

The ConfigurableItem object represents a single row from the ModuleConfiguration table. This is a single configurable "attribute" from the module. The interface consists read-only properties, one for each column in the ModuleConfiguration table. The Interface definition is as follows.

Interface ID

Constant | Value
IID_IMsmConfigurableItem | {4D6E6284-D21D-401E-84F6-909E00B50F71}

Properties

Property | Description
Name |
Format |
Type |
Context |
DefaultValue |
Attributes |
DisplayName |
Description |
HelpLocation |
HelpKeyword |

Methods

None.

C++

interface IMsmConfigurableItem : IDispatch


Name Property

[This is preliminary documentation and subject to change.]

The Name property returns the value from the Name column of the ModuleConfiguration table . It is the client's responsibility to free the BSTR when it is no longer needed. This is a read-only property.

Syntax

object.Name

Parameters

object
ConfigurableItem object

C++

See get_Name function.


get_Name Function

[This is preliminary documentation and subject to change.]

The get_Name function implements the Name property of the ConfigurableItem object.

IMsmConfigurableItem::get_Name

HRESULT get_Name(
  IMsmConfigurableItem* Name
);

Parameters

Name
[retval, out] A pointer to a location in memory with the name of a configurable item as listed in the Name column of the ModuleConfiguration table.

Return Values

Value | Meaning
E_INVALIDARG | Invalid argument.
S_OK | The function succeeded.
E_FAIL | No module is open.
E_OUTOFMEMORY | Out of memory.
ERROR_FUNCTION_FAILED as HRESULT | The function failed.
ERROR_INVALID_HANDLE as HRESULT | The function failed.

See Also

Merge Module Automation


Format Property

[This is preliminary documentation and subject to change.]

The Format property returns the value from the Format column of the ModuleConfiguration table. This is a read-only property.

Syntax

object.Format

Parameters

object
ConfigurableItem object

Remarks

This property can only have the following values.

Constant | Value
msmConfigurableItemText | 0
msmConfigurableItemKey | 1
msmConfigurableItemInteger | 2
msmConfigurableItemBitfield | 3

C++

See get_Format function.


get_Format Function

[This is preliminary documentation and subject to change.]

The get_Format function implements the Format property of the ConfigurableItem object.

IMsmConfigurableItem::get_Format

HRESULT get_Name(
  IMsmConfigurableItem* Format
);

Parameters

Format
[retval, out] A pointer to a location in memory with the format of a configurable item listed in the Format column of the ModuleConfiguration table.

Return Values

Value | Meaning
E_INVALIDARG | Invalid argument.
S_OK | The function succeeded.
E_FAIL | No module is open.
E_OUTOFMEMORY | Out of memory.
ERROR_FUNCTION_FAILED as HRESULT | The function failed.
ERROR_INVALID_HANDLE as HRESULT | The function failed.

See Also

Merge Module Automation


Type Property (ConfigurableItem Object)

[This is preliminary documentation and subject to change.]

The Type property returns the value from the Type column of the ModuleConfiguration table . It is the client's responsibility to free the BSTR when it is no longer needed. This is a read-only property.

Syntax

object.Type

Parameters

object
ConfigurableItem object

C++

See get_Type Function (ConfigurableItem Object).


get_Type Function (ConfigurableItem Object)

[This is preliminary documentation and subject to change.]

The get_Type function implements the Type property of the ConfigurableItem object.

IMsmConfigurableItem::get_Type

HRESULT get_Type(
  IMsmConfigurableItem* Type
);

Parameters

Type
[retval, out] A pointer to a location in memory with the format of a configurable item listed in the Type column of the ModuleConfiguration table.

Return Values

Value | Meaning
E_INVALIDARG | Invalid argument.
S_OK | The function succeeded.
E_FAIL | No module is open.
E_OUTOFMEMORY | Out of memory.
ERROR_FUNCTION_FAILED as HRESULT | The function failed.
ERROR_INVALID_HANDLE as HRESULT | The function failed.

See Also

Merge Module Automation


Context Property

[This is preliminary documentation and subject to change.]

The Context property returns the value from the Context column of the ModuleConfiguration table. It is the client's responsibility to free the BSTR when it is no longer needed. This is a read-only property.

Syntax

object.Context

Parameters

object
ConfigurableItem object

C++

See get_Context function


get_Context Function

[This is preliminary documentation and subject to change.]

The get_Context function implements the Context property of the ConfigurableItem object.

IMsmConfigurableItem::get_Context

HRESULT get_Context(
  IMsmConfigurableItem* Context
);

Parameters

Context
[retval, out] A pointer to a location in memory with the context of a configurable item listed in the context column of the ModuleConfiguration table.

Return Values

Value | Meaning
E_INVALIDARG | Invalid argument.
S_OK | The function succeeded.
E_FAIL | No module is open.
E_OUTOFMEMORY | Out of memory.
ERROR_FUNCTION_FAILED as HRESULT | The function failed.
ERROR_INVALID_HANDLE as HRESULT | The function failed.

See Also

Merge Module Automation


DefaultValue Property

[This is preliminary documentation and subject to change.]

The DefaultValue property returns the value from the DefaultValue column of the ModuleConfiguration table. It is the client's responsibility to free the BSTR when it is no longer needed. This is a read-only property.

Syntax

object.DefaultValue

Parameters

object
ConfigurableItem object

C++

See get_DefaultValue function


get_DefaultValue Function

[This is preliminary documentation and subject to change.]

The get_DefaultValue function implements the DefaultValue property of the ConfigurableItem object.

IMsmConfigurableItem::get_DefaultValue

HRESULT get_DefaultValue(
  IMsmConfigurableItem* DefaultValue
);

Parameters

DefaultValue
[retval, out] A pointer to a location in memory with the default value of a configurable item listed in the DefaultValue column of the ModuleConfiguration table.

Return Values

Value | Meaning
E_INVALIDARG | Invalid argument.
S_OK | The function succeeded.
E_FAIL | No module is open.
E_OUTOFMEMORY | Out of memory.
ERROR_FUNCTION_FAILED as HRESULT | The function failed.
ERROR_INVALID_HANDLE as HRESULT | The function failed.

See Also

Merge Module Automation


Attributes Property (ConfigurableItem Object)

[This is preliminary documentation and subject to change.]

The Attributes property returns the value from the Attributes column of the ModuleConfiguration table. This is a read-only property.

Syntax

object.Attributes

Parameters

object
ConfigurableItem object

C++

See get_Attributes function.


get_Attributes Function

[This is preliminary documentation and subject to change.]

The get_Attributes function implements the Attributes Property of the ConfigurableItem object.

IMsmConfigurableItem::get_Attributes

HRESULT get_Attributes(
  IMsmConfigurableItem* Attributes
);

Parameters

Attributes
[retval, out] A pointer to a location in memory with the format of a configurable item listed in the Attributes column of the ModuleConfiguration table.

Return Values

Value | Meaning
E_INVALIDARG | Invalid argument.
S_OK | The function succeeded.
E_FAIL | No module is open.
E_OUTOFMEMORY | Out of memory.
ERROR_FUNCTION_FAILED as HRESULT | The function failed.
ERROR_INVALID_HANDLE as HRESULT | The function failed.

See Also

Merge Module Automation


DisplayName Property

[This is preliminary documentation and subject to change.]

The DisplayName property returns the value from the DisplayName column of the ModuleConfiguration table. It is the client's responsibility to free the BSTR when it is no longer needed. This is a read-only property.

Syntax

object.DisplayName

Parameters

object
ConfigurableItem object

C++

See get_DisplayName function.


get_DisplayName Function

[This is preliminary documentation and subject to change.]

The get_DisplayName function implements the DisplayName property of the ConfigurableItem object.

IMsmConfigurableItem::get_DisplayName

HRESULT get_Type(
  IMsmConfigurableItem* DisplayName
);

Parameters

DisplayName
[retval, out] A pointer to a location in memory with the format of a configurable item listed in the DisplayName column of the ModuleConfiguration table.

Return Values

Value | Meaning
E_INVALIDARG | Invalid argument.
S_OK | The function succeeded.
E_FAIL | No module is open.
E_OUTOFMEMORY | Out of memory.
ERROR_FUNCTION_FAILED as HRESULT | The function failed.
ERROR_INVALID_HANDLE as HRESULT | The function failed.

See Also

Merge Module Automation


Description Property (ConfigurableItem Object)

[This is preliminary documentation and subject to change.]

The Description property returns the value from the Description column of the ModuleConfiguration table. It is the client's responsibility to free the BSTR when it is no longer needed. This is a read-only property.

Syntax

object.Description

Parameters

object
ConfigurableItem object

C++

See get_Description function


get_Description Function

[This is preliminary documentation and subject to change.]

The get_Description function implements Description Property of the ConfigurableItem object.

IMsmConfigurableItem::get_Type

HRESULT get_Description(
  IMsmConfigurableItem* Description
);

Parameters

Description
[retval, out] A pointer to a location in memory with the description of a configurable item listed in the Description column of the ModuleConfiguration table.

Return Values

Value | Meaning
E_INVALIDARG | Invalid argument.
S_OK | The function succeeded.
E_FAIL | No module is open.
E_OUTOFMEMORY | Out of memory.
ERROR_FUNCTION_FAILED as HRESULT | The function failed.
ERROR_INVALID_HANDLE as HRESULT | The function failed.

See Also

Merge Module Automation


HelpLocation Property

[This is preliminary documentation and subject to change.]

The HelpLocation property returns the value from the HelpLocation column of the ModuleConfiguration table. It is the client's responsibility to free the BSTR when it is no longer needed. This is a read-only property.

Syntax

object.HelpLocation

Parameters

object
ConfigurableItem object

C++

See get_HelpLocation function.


get_HelpLocation Function

[This is preliminary documentation and subject to change.]

The get_HelpLocation function implements the HelpLocation property of the ConfigurableItem object.

IMsmConfigurableItem::get_HelpLocation

HRESULT get_Type(
  IMsmConfigurableItem* HelpLocation
);

Parameters

HelpLocation
[retval, out] A pointer to a location in memory with the help location of a configurable item listed in the HelpLocation column of the ModuleConfiguration table.

Return Values

Value | Meaning
E_INVALIDARG | Invalid argument.
S_OK | The function succeeded.
E_FAIL | No module is open.
E_OUTOFMEMORY | Out of memory.
ERROR_FUNCTION_FAILED as HRESULT | The function failed.
ERROR_INVALID_HANDLE as HRESULT | The function failed.

See Also

Merge Module Automation


HelpKeyword Property

[This is preliminary documentation and subject to change.]

The HelpKeyword property returns the value from the HelpKeyword column of the ModuleConfiguration table. It is the client's responsibility to free the BSTR when it is no longer needed. This is a read-only property.

Syntax

object.HelpKeyword

Parameters

object
ConfigurableItem object

C++

See get_HelpKeyword function.


get_HelpKeyword Function

[This is preliminary documentation and subject to change.]

The get_HelpKeyword function implements the HelpKeyword property of the ConfigurableItem object.

IMsmConfigurableItem::get_HelpKeyword

HRESULT get_Type(
  IMsmConfigurableItem* HelpKeyword
);

Parameters

HelpKeyword
[retval, out] A pointer to a location in memory with the help key word of a configurable item listed in the HelpKeyword column of the ModuleConfiguration table.

Return Values

Value | Meaning
E_INVALIDARG | Invalid argument.
S_OK | The function succeeded.
E_FAIL | No module is open.
E_OUTOFMEMORY | Out of memory.
ERROR_FUNCTION_FAILED as HRESULT | The function failed.
ERROR_INVALID_HANDLE as HRESULT | The function failed.

See Also

Merge Module Automation


ConfigureModule Object

[This is preliminary documentation and subject to change.]

The ConfigureModule object is an interface implemented by the client. MergeMod.dllcalls methods on the IMsmConfigureModule interface to request that the client tool provide configuration information. The module is configured based on the client's responses to calls on this interface.

Interface ID

Constant | Value
IID_IMsmConfigureModule | {AC013209-18A7-4851-8A21-2353443D70A0}

Properties

None.

Methods

Method | Description
ProvideTextData |
ProvideIntegerData |

C++

interface IMsmConfigureModule : IDispatch


ProvideTextData Method

[This is preliminary documentation and subject to change.]

The ProvideTextData method is called by MergeMod.dll to retrieve text data from the client tool. MergeMod.dllprovides the Name from the corresponding entry in the ModuleConfiguration table.

The tool should return S_OK and provide the appropriate customization text in ConfigData. The client tool is responsible for allocating the data, but MergeMod.dllis responsible for releasing the memory. This argument MUST be a BSTR object. LPCWSTR is NOT accepted.

If the tool does not provide any configuration data for this Name value, the function should return S_FALSE. In this case MergeMod.dllignores the value of the ConfigData argument and uses the Default value from the ModuleConfiguration table.

Any return code other than S_OK or S_FALSE will cause an error to be logged (if a log is open) and will result in the merge failing.

Because this function follows standard BSTR convention, NULL is equivalent to the empty string.

Syntax

object.ProvideTextData(Name,ConfigData)

Parameters

object
ConfigureModule object
Name
Name of item for which data is being retrieved.
ConfigData
Pointer to customization text.

C++

See ProvideTextData function.


ProvideTextData Function

[This is preliminary documentation and subject to change.]

The ProvideTextData function implements the ProvideTextData method of the ConfigureModule object.

IMsmConfigureModule::ProvideTextData Mergemod.dll version 1.5 or later.

HRESULT ProvideTextData(
  BSTR Name
  BSTR* ConfigData
);

Parameters

Name
[in] If the tool does not provide any configuration data for this Name value, the function should return S_FALSE. In this case MergeMod.dllignores the value of the ConfigData argument and uses the Default value from the ModuleConfiguration table.
ConfigData
[retval, out] The tool should return S_OK and provide the appropriate customization text in ConfigData. The client tool is responsible for allocating the data, but MergeMod.dll is responsible for releasing the memory. This argument must be a BSTR object. LPCWSTR is not accepted.

Return Values

Any return code other than S_OK or S_FALSE causes an error to be logged (if a log is open) and results in the merge failing.

Value | Meaning
S_FALSE |
S_OK |

See Also

Merge Module Automation


ProvideIntegerData Method

[This is preliminary documentation and subject to change.]

The ProvideIntegerData method is called by MergeMod.dll to retrieve integer data from the client tool.

MergeMod.dll provides the Name from the corresponding entry in the ModuleConfiguration table.

The tool should return S_OK and provide the appropriate customization integer in ConfigData.

If the tool does not provide any configuration data for this Name value, the function should return S_FALSE. In this case MergeMod.dll ignores the value of the ConfigData argument and uses the Default value from the ModuleConfiguration table.

The client is called at most once for each row in the ModuleConfiguration table. Under no circumstances does the client receive multiple calls for the same "Name" value, but it is possible for an entry in the ModuleConfiguration table to not cause a call to the client at all. This could happen if no row in the ModuleSubstitution table uses the property.

Syntax

object.ProvideIntegerData(Name,ConfigData)

Parameters

object
ConfigureModule object
Name
Name of item for which data is being retrieved.
ConfigData
Pointer to customization text.

C++

See ProvideIntegerData function.


ProvideIntegerData Function

[This is preliminary documentation and subject to change.]

The ProvideIntegerData function implements the ProvideIntegerData method of the ConfigureModule object.

IMsmConfigureModule::ProvideIntegerData Mergemod.dll version 1.5 or later.

HRESULT ProvideIntegerData(
  BSTR Name
  BSTR* ConfigData
);

Parameters

Name
[in] If the tool does not wish to provide any configuration data for this Name value, the function should return S_FALSE. In this case MergeMod.dll ignores the value of the ConfigData argument and will use the Default value from the ModuleConfiguration table.
ConfigData
[retval, out] The tool should return S_OK and provide the appropriate customization text in ConfigData. The client tool is responsible for allocating the data, but MergeMod.dll is responsible for releasing the memory. This argument must be a BSTR object. LPCWSTR is not accepted.

Return Values

Any return code other than S_OK or S_FALSE causes an error to be logged (if a log is open) and results in the merge failing.

Value | Meaning
S_FALSE |
S_OK |

See Also

Merge Module Automation


CMSM Special Format

[This is preliminary documentation and subject to change.]

Certain values used with configurable merge modules require special text handling. A text string described as being in "CMSM Special Format" treats the semicolon (;) and equals (=) characters as reserved characters used to invoke the client merge tool or MergeMod.dll.

CMSM Special format is currently used in the following locations:

  • The Row column of the ModuleSubstitution table.
  • The Value column of the ModuleSubstitution table.
  • The ContextData column of the ModuleConfiguration table when Bitfield is the value in the Format column.
  • The ContextData column of the ModuleConfiguration table when Text is the value in the Format column and Enum is the value in the Type column.
  • The DefaultValue column of the ModuleConfiguration table when Key is the value in the Format column.
  • Configurable items in the Key format used by the ProvideTextData method.

To enter literal semicolons or equal characters into a value in CMSM special format, prefix the character with a backslash character ('\'). A literal backslash can be represented by two backslashes. A single character prefixed by a single backslash is translated into the single character, even if escaping the character is not required.

If a semicolon or equals character is not prefixed by a backslash yet does not have a defined behavior in the context of the value, the resulting string is undefined. For example, the DefaultValue column of the ModuleConfiguration table is in CMSM special format for all Key items because the semicolon character is the column delimiter. Although the equal character has no special meaning in this string, literal equal characters must still be escaped in this string.


Semantic Types

[This is preliminary documentation and subject to change.]

The following entries in the Format, Type, and ContextData columns of the ModuleConfiguration table specify the semantic type of information being substituted into the configurable item specified in the Name column of this table.

Text Format Types

Format | Type | ContextData | Description
Text |  |  | Arbitrary text. See Arbitrary Text Type.
Text | Enum | <A>=<a>;<B>=<b>;<C>=<c> | Value selected from a set. See Enum Type.
Text | Formatted |  | Value meeting the definition of Formatted Text in the installer. See Formatted Type.
Text | RTF |  | An RTF text string. See RTF Type.
Text | Identifier |  | A text string conforming to a Windows Installer Identifier.

Integer Format Types

Format | Type | ContextData | Description
Integer |  |  | Any integer value. See Arbitrary Integer Type.

Key Format Types

Format | Type | ContextData | Description
Key | Assembly | AssemblyContext | COM+ assembly isolation context. See Assembly Type.
Key | Binary | Bitmap | Foreign key to a Binary table row holding a bitmap for use in UI. See Binary Type.
Key | Binary | Icon | Foreign key to a Binary table row holding an Icon for use in UI. See Binary Type.
Key | Binary | EXE | Foreign key to a Binary table row holding a 32bit EXE. See Binary Type.
Key | Binary | EXE64 | Foreign key to a Binary table row holding a 32 or 64bit EXE. See Binary Type.
Key | Icon | ShortcutIcon | Foreign key to an Icon table row holding an Icon for use by a shortcut. See Icon Type.
Key | Dialog | DialogNext | Foreign key to a Dialog table row. See Dialog Type.
Key | Dialog | DialogPrev | Foreign key to a Dialog table row. See Dialog Type.
Key | Directory | IsolationDir | Foreign key to a Directory table row where isolated files belong. See Directory Type.
Key | Directory | ShortcutLocation | Foreign key to a Directory table row where a shortcut should be installed. See Directory Type.
Key | Property |  | Foreign key to a property row. See Property Type.
Key | Property | Public | Foreign key to a property row. See Property Type.
Key | Property | Private | Foreign key to a property row. See Property Type.

Bitfield Format Types

Format | Type | ContextData | Description
Bitfield |  | <mask>;<A>=<a>;<B>=b | Changes a subset of bits in a column. See Arbitrary Bitfield Type.


Text Format Types

[This is preliminary documentation and subject to change.]

The text format types of configurable data may be text strings of any length. Embedded NULLs are not allowed.

The following Text Format types exist:

Arbitrary Text

RTF

Formatted

Enum

Identifier Type

Configurable items of the Text Format Type are used in non-binary database fields and in general could be replaced by any string of any length. However, particular configurable items also have semantic restrictions. For example, a configurable item that is required to be a foreign key into a specific table has additional semantic restrictions. Such semantic restrictions are not enforced by Mergemod.dll and therefore module authors should be prepared to handle any string that satisfies the specified Text Format type.


Arbitrary Text Type

[This is preliminary documentation and subject to change.]

The Arbitrary Text Type of semantic type is one of the Text Format Types. This type consists of an arbitrary text string of any length provided by the user. The merge tool substitutes this arbitrary string into the templates specified in the Value column of the ModuleSubstitution table.

To specify a configurable item of this type, module authors should enter the name of the text string into the Name column, enter "0" into the Format column, and leave blank the Type and ContextData columns of the ModuleConfiguration table.The arbitrary text string may be in any language compatible with the code page of the database. For details, see Code Page Handling (Windows Installer). NULL is a valid value for the text string unless the msmConfigItemNonNullable has been included in the Attributes field of the ModuleConfiguration table.


RTF Type

[This is preliminary documentation and subject to change.]

The RTF Type of semantic type is one of the Text Format Types. This type consists of an arbitrary text string in the Rich Text Format (RTF) of any length provided by the user. The merge tool substitutes this string into the templates specified in the Value column of the ModuleSubstitution table.

To specify a configurable item of this type, module authors should enter the name of the text string into the Name column, enter "0" into the Format column, enter "RTF" into the Type column, and leave blank the ContextData column of the ModuleConfiguration table.The string may be in any language compatible with the code page of the database. See Code Page Handling (Windows Installer). NULL is a valid value for the text string unless the msmConfigItemNonNullable has been included in the Attributes field of the ModuleConfiguration table.


Formatted Type

[This is preliminary documentation and subject to change.]

The Formatted Type of semantic type is one of the Text Format Types. This type consists of an arbitrary text string of any length provided by the user and in the Windows Installer formatted text format. For details, see Formatted. The merge tool substitutes this string into the templates specified in the Value column of the ModuleSubstitution table.

To specify a configurable item of this type, module authors should enter the name of the text string into the Name column, enter "0" into the Format column, enter "Formatted" into the Type column, and leave blank the ContextData column of the ModuleConfiguration table.The string may be in any language compatible with the code page of the database. For details, see Code Page Handling (Windows Installer). NULL is a valid value for the text string unless the msmConfigItemNonNullable has been included in the Attributes field of the ModuleConfiguration table.


Enum Type

[This is preliminary documentation and subject to change.]

The Enum Type of semantic type is one of the Text Format Types. This type consists of a text string chosen by the user from a set of choices. The merge tool substitutes the selected string selected into the templates specified in the Value column of the ModuleSubstitution table.

To specify a configurable item of this type, module authors should enter the name of the text string into the Name column, enter "0" into the Format column, enter "Enum" into the Type column, and enter the list of possible strings in the ContextData column of the ModuleConfiguration table. The list of possible strings must be provided as a list of strings deliminated by semicolons. Each choice must be in the form "Name=Value". A literal semicolon can be added to the value by prefixing the semicolon with a backslash character. NULL is a valid value unless the msmConfigItemNonNullable has been included in the Attributes field of the ModuleConfiguration table.


Identifier Type

[This is preliminary documentation and subject to change.]

The Identifier Type of semantic type is one of the Text Format Types. This type consists of an text string provided by the user in the format of a Windows Installer Identifier. The merge tool substitutes this string into the templates specified in the Value column of the ModuleSubstitution table.

To specify a configurable item of this type, module authors should enter the name of the text string into the Name column, enter "0" into the Format column, enter "Identifier" into the Type column, and leave blank the ContextData column of the ModuleConfiguration table.The string may be in any language compatible with the code page of the database. See Code Page Handling (Windows Installer). NULL is a valid value for the text string unless the msmConfigItemNonNullable has been included in the Attributes field of the ModuleConfiguration table.


Integer Format Types

[This is preliminary documentation and subject to change.]

The Integer Format Types of configurable data may be used in either text or integer database fields. The msmConfigItemNonNullable attribute is implicit in this data format and does not need to be set. NULL is never a valid value for this type.

The following Integer Format type exists.

Arbitrary Integer Type

Configurable items of the Integer Format Type are used in either text or integer columns and in general could be replaced by any positive or negative integer. However, particular configurable items may also have characteristic semantic restrictions. For example, a particular configurable item required to be an interger between 0 and 100 has and additional semantic restriction. Such restrictions are not enforced by Mergemod.dll and therefore module authors should be prepared to handle any string that satisfies the specified Integer Format type.


Arbitrary Integer Type

[This is preliminary documentation and subject to change.]

The Arbitrary Integer Type of semantic type is one of the Integer Format Types. This type of configurable item is an integer provided by the user. The merge tool substitutes this integer into the templates specified in the Value column of the ModuleSubstitution table.

To specify a configurable item of this type, module authors should enter the name of the text string into the Name column, enter "2" into the Format column, and leave blank the Type and ContextData columns of the ModuleConfiguration table. The Type and ContextData columns are reserved and must be NULL.


Key Format Types

[This is preliminary documentation and subject to change.]

The Key Format Types of configurable data may be used in text fields to provide a key into a database table. The msmConfigItemNonNullable attribute is implicit in this data format and does not need to be set. NULL is never a valid value for this type. Responses to all Key format items must be in CMSM Special Format.

The following Key Format types exist:

Directory Type

Assembly Type

Property Type

Dialog Type

Binary Type

Icon Type

Configurable items of the Key Format Type are used in text columns to provide a database key and in general could be replaced by any text string. The individual types may have additional syntactic restrictions, but these restrictions are not enforced by MergeMod.dll. Particular configurable items may also have characteristic semantic restrictions. For example, a particular configurable item may be required to be a key into the Binary table to a row containing a bitmap image. Such restrictions are not enforced by Mergemod.dll and therefore module authors should be prepared to handle any string that satisfies the specified Key Format type. Unless otherwise specified by semantic meaning or attributes, NULL is a valid response.


Directory Type

[This is preliminary documentation and subject to change.]

The Directory Type of semantic type is one of the Key Format Types, which consists of a foreign key into the Directory table provided by the user.

The merge tool must substitute a valid Windows Installer Identifier for items of this type. Mergemod.dll does not enforce this restriction and it is up to the merge tool to ensure that the user provides a valid key into the Directory table.

A configurable item of the Directory type should only modify the destination directory of the installation and not modify the source image. A configurable item of this type should therefore only modify foreign keys to the Directory table and not modify the Directory table directly.

Because the Directory_ column of the Component table is non-nullable, NULL is an invalid value for a configurable item of this type even if the msmConfigItemNonNullable is not set in the Attributes column.

The Directory type may be used with two kinds of ContextData.

IsolationDirectory ContextData

A configurable merge module may use this type to enable the user to provide a destination directory for files in the module. The merge tool substitutes the directory's identifier into the templates in the Value column of the ModuleSubstitution table. To specify a configurable item of this type, module authors should enter the name of the directory into the Name column, enter "1" into the Format column, enter "Directory" into the Type column, and enter "IsolationDirectory" into the ContextData column of the ModuleConfiguration table.

ShortcutLocation ContextData

A configurable merge module may use this type to enable the user to provide a destination directrory for shortcuts in the module. The merge tool substitutes the shortcut's identifier into the templates in the Value column of the ModuleSubstitution table. To specify a configurable item of this type, module authors should enter the name of the directory into the Name column, enter "1" into the Format column, enter "Directory" into the Type column, and enter "ShortcutLocation" into the ContextData column of the ModuleConfiguration table.


Assembly Type

[This is preliminary documentation and subject to change.]

The Assembly Type of semantic type is one of the Key Format Types. This type consists of a foreign key into the MsiAssembly table provided by the user. The type may be used to enable users to configure foreign keys to Win32 or .NET Frameworks assemblies.

The merge tool must substitute a Windows Installer Identifier for items of this type. Mergemod.dll does not enforce this and it is up to the merge tool to ensure that the user provides a valid key into the MsiAssembly table. The merge tool substitutes the assembly's identifier into the templates in the Value column of the ModuleSubstitution table. To specify a configurable item of this type, module authors should enter the name of the directory into the Name column, enter "1" into the Format column, enter "Directory" into the Type column, and enter "ShortcutLocation" into the ContextData column of the ModuleConfiguration table.

NULL is a valid value for this type unless the msmConfigItemNonNullable has been included in the Attributes field of the ModuleConfiguration table.


Property Type

[This is preliminary documentation and subject to change.]

The Property Type of semantic type is one of the Key Format Types. This type consists of a foreign key into the Property table provided by the user.

The merge tool must substitute a valid Windows Installer Identifier for items of this type. Mergemod.dll does not enforce this restriction and it is up to the merge tool to ensure that the user provides a valid key into the Property table. The primary keys of the Property table are the property names.

NULL is a valid value for this type unless the msmConfigItemNonNullable has been included in the Attributes field of the ModuleConfiguration table.

The Property type may be used with the following kinds of ContextData.

Null ContextData

A configurable merge module may use this type to enable the user to provide a property name to a database table in the module. The merge tool substitutes the property's identifier into the templates in the Value column of the ModuleSubstitution table. To specify a configurable item of this type, module authors should enter the name of the configurable item into the Name column, enter "1" into the Format column, enter "Property" into the Type column, and leave blank the ContextData column of the ModuleConfiguration table.

Public ContextData

A configurable merge module may use this type to enable the user to provide the name of a public property to a database table in the module. The merge tool substitutes the property's identifier into the templates in the Value column of the ModuleSubstitution table. To specify a configurable item of this type, module authors should enter the name of the configurable item into the Name column, enter "1" into the Format column, enter "Property" into the Type column, and enter "Public" into the ContextData column of the ModuleConfiguration table.

Private ContextData

A configurable merge module may use this type to enable the user to provide the name of a private property to a database table in the module. The merge tool substitutes the property's identifier into the templates in the Value column of the ModuleSubstitution table. To specify a configurable item of this type, module authors should enter the name of the configurable item into the Name column, enter "1" into the Format column, enter "Property" into the Type column, and enter "Private" into the ContextData column of the ModuleConfiguration table.


Dialog Type

[This is preliminary documentation and subject to change.]

The Dialog Type of semantic type is one of the Key Format Types. This type consists of a foreign key into the Dialog table provided by the user.

The merge tool must substitute a valid Windows Installer Identifier for items of this type. Mergemod.dll does not enforce this restriction and it is up to the merge tool to ensure that the user provides a valid key into the Dialog table.

NULL is a valid value for this type unless the msmConfigItemNonNullable has been included in the Attributes field of the ModuleConfiguration table.

The Dialog type may be used with the following kinds of ContextData.

DialogNext ContextData

A configurable merge module may use this type to enable the user to provide a foreign key into the Dialog Table. To specify a configurable item of this type, module authors should enter the name of the configurable item into the Name column, enter "1" into the Format column, enter "Dialog" into the Type column, and enter "DialogNext" into the ContextData column of the ModuleConfiguration table.

DialogPrev ContextData

A configurable merge module may use this type to enable the user to provide a foreign key into the Dialog Table. To specify a configurable item of this type, module authors should enter the name of the configurable item into the Name column, enter "1" into the Format column, enter "Dialog" into the Type column, and enter "DialogPrev" into the ContextData column of the ModuleConfiguration table.


Binary Type

[This is preliminary documentation and subject to change.]

The Binary Type of semantic type is one of the Key Format Types. This type consists of a key into the Binary table provided by the user.

The merge tool must substitute a valid Windows Installer Identifier for items of this type. Mergemod.dll does not enforce this restriction and it is up to the merge tool to ensure that the user provides a valid key into the Binary table.

NULL is a valid value for this type unless the msmConfigItemNonNullable has been included in the Attributes field of the ModuleConfiguration table.

The Binary type may be used with the following kinds of ContextData.

Bitmap ContextData

A configurable merge module may use this type to enable the user to provide a foreign key to a row in the Binary Table that contains a bitmap image. Mergmod.dll does not guarantee any specific size or type of bitmap and the merge tool must ensure that the data is a valid image. To specify a configurable item of this type, module authors should enter the name of the configurable item into the Name column, enter "1" into the Format column, enter "Binary" into the Type column, and enter "Bitmap" into the ContextData column of the ModuleConfiguration table.

Icon ContextData

A configurable merge module may use this type to enable the user to provide a foreign key to a row in the Binary Table that contains an icon image. Mergmod.dll does not guarantee any specific size or type of icon and the merge tool must ensure that the data is a valid image. To specify a configurable item of this type, module authors should enter the name of the configurable item into the Name column, enter "1" into the Format column, enter "Binary" into the Type column, and enter "Icon" into the ContextData column of the ModuleConfiguration table. This type is not appropriate for use in an advertisement table.

EXE ContextData

A configurable merge module may use this type to enable the user to provide a foreign key to a row in the Binary Table that contains a 32-bit executable image. Mergmod.dll does not validate the data is valid and the merge tool must ensure that the data is a valid PE file. To specify a configurable item of this type, module authors should enter the name of the configurable item into the Name column, enter "1" into the Format column, enter "Binary" into the Type column, and enter "EXE" into the ContextData column of the ModuleConfiguration table.

EXE64 ContextData

A configurable merge module may use this type to enable the user to provide a foreign key to a row in the Binary Table that contains either a 32-bit or 64-bit executable image. Mergmod.dll does not validate the data is valid and the merge tool must ensure that the data is a valid PE file. To specify a configurable item of this type, module authors should enter the name of the configurable item into the Name column, enter "1" into the Format column, enter "Binary" into the Type column, and enter "EXE64" into the ContextData column of the ModuleConfiguration table.


Icon Type

[This is preliminary documentation and subject to change.]

The Icon Type of semantic type is one of the Key Format Types. This type consists of a key into the Icon table provided by the user.

The merge tool must substitute a valid Windows Installer Identifier for items of this type. Mergemod.dll does not enforce this restriction and it is up to the merge tool to ensure that the user provides a valid key into the Icon table.

NULL is a valid value for this type unless the msmConfigItemNonNullable has been included in the Attributes field of the ModuleConfiguration table.

The Binary type may be used with the following kinds of ContextData.

Icon ContextData

A configurable merge module may use this type to enable the user to provide a foreign key to a row in the Icon Table that contains an image suitable for use as a shortcut icon. To specify a configurable item of this type, module authors should enter the name of the configurable item into the Name column, enter "1" into the Format column, enter "Icon" into the Type column, and enter "Icon" into the ContextData column of the ModuleConfiguration table. This type is not appropriate for use in a user interface table. To modify a key to the Icon table in these tables see Icon ContextData under Binary Type.


Bitfield Format Types

[This is preliminary documentation and subject to change.]

The Bitfield Format Types of configurable data may be used in integer database fields. The user should choose a value from a specified subset. This is by convention only and is not enforced by Mergemod.dll. The msmConfigItemNonNullable attribute is implicit in this data format and does not need to be set. NULL is never a valid value for this type.

The following Bitfield Format type exists.

Arbitrary Bitfield Type

Configurable items of the Bitfield Format Type are used in integer columns and in general could be replaced by any integer. The user should choose a value from a specified subset. This is by convention only, however, and is not enforced by Mergemod.dll. The author should prepare the module to handle any value.


Arbitrary Bitfield Type

[This is preliminary documentation and subject to change.]

The "Bitfield" type with no context requests that the user provide an integer whose value is used to set one or more bits in a bitfield. This text may be in any language compatible with the code page of the database.

The Arbitrary Bitfield Type of semantic type is one of the Bitfield Types. This type consists of an integer chosen by the user from a set of choices. The merge tool substitutes the selected integer into the templates specified in the Value column of the ModuleSubstitution table. To specify a configurable item of this type, module authors should enter the name of the item into the Name column, enter "3" into the Format column, leave the Type column blank, and enter the list of possible integers in the ContextData column of the ModuleConfiguration table.

The Type column is reserved and must be NULL. The entry in the ContextData column for all Bitfield Format types must be in the form "<mask>;<Name>=<value>;<Name>=<value>....", where <mask> is an integer value indicating the bits of interest, <Name> is a localizable display name for the choice, and <value> is a decimal integer value. The context column is in use CMSM Special Format and for all bitfield types. A literal "=" or ";" character can be entered in the <Name> field by prefixing it with a backslash ('\') character.


Configurable Component Example

[This is preliminary documentation and subject to change.]

In this example, the following ModuleConfiguration and ModuleSubstitution tables allows the module consumer to independently configure the Password attribute for an edit control, the checksum attribute for a file, and the compressed attribute for the same file.

ModuleSubstitution Table

Table | Row | Column | Value
Control | Dialog1;Edit1 | Attributes | [=Password]
File | File1 | Attributes | [=Checksum][=Compressed]

ModuleConfiguration Table

Name | Format | Type | ContextData | DefaultValue | Attributes | DisplayName | Description
Password | Bitfield |  | 2097152;True=2097152;False=0 | 0 | 0 |  |
Checksum | Bitfield |  | 1024;Checksum=1024;No Checksum=0 | 0 | 0 |  |
Compressed | Bitfield |  | 24576;Compressed=16384;Uncompressed=8192 | 8192 | 0 |  |


Merge Module ICE Reference

[This is preliminary documentation and subject to change.]

The following list provides links to each Merge Module ICE.

ICEM | Brief description of Merge Module ICE
ICEM01 | Validates that the ICE mechanism is working.
ICEM02 | Validates that all module exclusions and dependencies relate to the current module.
ICEM03 | Validates that all actions in the module are either base actions or derive from a base action.
ICEM04 | Verifies that the merge module's required empty tables are indeed empty.
ICEM05 | Checks for invalid associations with components.
ICEM06 | Checks for invalid references to features by the module.
ICEM07 | Validates that the order of files in the sequence tables and in MergeModule.CABinet file match.
ICEM08 | Ensures that a module does not exclude something it depends on.
ICEM09 | Verifies that the merge module safely handles predifined directories.
ICEM10 | Verifies that a merge module does not contain disallowed properties in the Property Table.
ICEM11 | Verifies that a Configurable Merge Module lists the ModuleConfiguration table and ModuleSubstitution table in the ModuleIgnoreTable table of the module.
ICEM12 | Verifies that in a ModuleSequence table, standard actions have Sequence numbers and custom actions have BaseAction and After values.

See Also

Validating Merge Modules


ICEM01

[This is preliminary documentation and subject to change.]

ICEM01 validates that the ICE mechanism is working. This ICE uses the Time property to get the time and returns either the system time or None.

Merge module ICEs are stored in a merge module .cub file called Mergemod.cub and not in the .cub file containing the ICEs used for package validation.

Result

ICEM01 posts a message giving the time the installer called ICEM01. This ICE should never return an error.

See Also

Merge Module ICE Reference


ICEM02

[This is preliminary documentation and subject to change.]

ICEM02 verifies that all the module dependencies and exclusions are related to the current module.

Merge module ICEs are stored in a merge module .cub file called Mergemod.cub and not in the .cub file containing the ICEs used for package validation.

Result

ICEM02 posts error messages if the module database attempts to specify dependencies or exclusions that do not relate to the current module. ICEM02 posts an error message if the module database attempts to specify the current module as dependent or as excluded by itself.

Example

ICEM02 would post the following error messages for a module containing the database entries shown below.

The dependency OtherModule.GUID2.1033.OtherModule.GUID3.0 in the
ModuleDependency table creates a dependency for an unrelated module. A
module can only define dependencies for itself

This module is listed as depending on itself!

The exclusion OtherModule.GUID2.1033.OtherModule.GUID3.0 in the
ModuleExclusion table creates an excluded module for an unrelated
module. A module can only define exclusions for itself.

This module excludes itself from the target database!

ModuleSignature Table

ModuleID | Language | Version
MyModule.GUID1 | 1033 | 1.0

ModuleDependency Table

ModuleID | ModuleLanguage | RequiredID | RequiredLanguage | RequiredVersion
OtherModule.GUID2 | 1033 | OtherModule.GUID3 | 0 | 1.0
MyModule.GUID1 | 1033 | MyModule.GUID1 | 1033 | 1.2

ModuleExclusion Table (partial)

ModuleID | ModuleLanguage | ExcludedID | ExcludedLanguage
OtherModule.GUID2 | 1033 | OtherModule.GUID3 | 0
MyModule.GUID1 | 1033 | MyModule.GUID1 | 1033

The merge module ICE posts the first error because the of the first row in the ModuleDependency table, which does not specify a required dependency for the current module specified in the ModuleSignature table. The dependencies of a module can only be specified in its own ModuleDependency table. If OtherModule.GUID3 is required by the current module, replace the first two columns of the row with the data from the ModuleSignature table. If OtherModule.GUID3 is not required by this module, delete this row.

The merge module ICE posts the second error because a module cannot specify a dependency upon itself.

The merge module ICE posts the third error because of the first row in the ModuleExclusion table, which does not specify a required exclusion for the current module specified in the ModuleSignature table. The exclusions of a module can only be specified in its own ModuleExclusion table. If the current module excludes OtherModule.GUID3, replace the first two columns of the row with the data from the ModuleSignature table. If the current module does not exclude OtherModule.GUID3, delete this row.

The merge module ICE posts the fourth error because a module cannot specify that it exclude itself.

See Also

Merge Module ICE Reference


ICEM03

[This is preliminary documentation and subject to change.]

ICEM03 verifies that all actions in the module are either base actions or derive from a valid base action.

Merge module ICEs are stored in a merge module .cub file called Mergemod.cub and not in the .cub file containing the ICEs used for package validation.

Result

ICEM03 posts the error messages for a module containing actions in a sequence table that is not a base action or derived from a valid base action.

Example

ICEM03 posts the following error messages for a module containing the database entries shown below.

The action 'Action1' in the 'ModuleInstallExecuteSequence' table is
orphaned. It is not a valid base action and does not derive from a
valid base action.
The action 'Action2' in the 'ModuleInstallExecuteSequence' table is
orphaned. It is not a valid base action and does not derive from a
valid base action.

ModuleInstallExecuteSequence Table

Action | Sequence | BaseAction | After | Condition
Action1 |  | Action2 | 0 |
Action2 |  | Action1 | 0 |

ICEM03 posts errors for these two actions because they refer to each other as base actions in the ModuleInstallExecuteSequence table. All actions in the ModuleAdminUISequence, ModuleAdminExecuteSequence, ModuleAdvtUISequence, ModuleAdvtExecuteSequence, ModuleInstallUISequence, and ModuleInstallExecuteSequence tables must either be base actions or derive their position from the combination of another action and a before and after flag.

To fix this error, determine the base actions for the two actions. Add a record for the base actions with a default sequence number. For Action1 and Action2 enter the base action names in the BaseAction column and 0 or 1 in the After column.

See Also

Merge Module ICE Reference


ICEM04

[This is preliminary documentation and subject to change.]

ICEM04 verifies that the Merge Module's required empty tables are indeed empty. Failure to fix an error reported by ICEM04 can result in improper merging of the Merge Module.

Result

ICEM04 posts an error when the Merge Module's required empty tables are not empty

Example

ICEM04 posts the following error messages for a module containing the database entries shown below.

An empty FeatureComponents table is required in a Merge Module.

The Merge Module contains the 'ModuleInstallExecuteSequence' table. It
must therefore have an empty 'InstallExecuteSequence' table.

Action 'CostInitialize' found in the AdvtExecuteSequence table. This
table must be empty in a Merge Module

AdvtExecuteSequence Table (partial)

Action | Sequence
CostInitialize | 1

Contents of MergeModule (partial)

  • ModuleInstallExecuteSequence
  • ModuleAdvtExecuteSequence
  • InstallUISequence

Another possible error (not evident with the Merge Module example shown) is:

Feature-Component '[1].[2]' found in the FeatureComponents table. The
FeatureComponents table must be empty in a Merge Module.

If a Merge Module contains a Module Sequence table, it must contain the corresponding empty Sequence table (regardless of whether or not the Module Sequence table itself is empty). For example, if the Merge Module contains the ModuleAdminExecuteSequence table, it must also contain an empty AdminExecuteSequence table.

The FeatureComponents table is required in all Merge Modules and must be empty.

To fix the errors, perform the following:

  1. Add an empty FeatureComponents table to the Merge Module.
  2. Add an empty InstallExecuteSequence table to the Merge Module.
  3. Remove the 'CostInitialize' action from the AdvtExecuteSequence table. This table must be empty in a Merge Module. Actions should only appear in the ModuleAdvtExecuteSequence table

Tables used during execution

  • FeatureComponents Table
  • Module*Sequence tables and corresponding *Sequence tables.

See Also

About Merge Modules, Merge Module ICE Reference


ICEM05

[This is preliminary documentation and subject to change.]

ICEM05 verifies that the merge module is correctly associated with components in the module. Incorrectly associating a component with a module causes the component to be incorrectly associated with the target database.

Merge module ICEs are stored in a merge module .cub file called Mergemod.cub and not in the .cub file containing the ICEs used for package validation.

Result

ICEM05 posts an error if the module database incorrectly associates components and the module.

Example

ICEM05 posts the following error messages for a module containing the database entries shown below.

The component Component2.OtherModule.GUID2.1033 in the
ModuleComponents table does not belong to this Merge Module.
The component Component1.MyModule.GUID1.1033 in the ModuleComponents
table is not listed in the Component table.
The component 'Component3' in the Component table is not listed in the
ModuleComponents table.

ModuleSignature Table

ModuleID | Language | Version
MyModule.GUID1 | 1033 | 1.0

ModuleComponents Table

Component | ModuleID | Language
Component1 | MyModule.GUID1 | 1033
Component2 | OtherModule.GUID2 | 1033

Component Table (partial)

Component | ComponentID
Component3 | GUID4
Component2 | GUID5

The merge module ICE reports the first error because the ModuleComponents table attempts to associate a component with another module that is not the current module specified in the ModuleSignature table. To fix this, change the ModuleID and Language columns of the ModuleComponents record for Component2 to that for the current module, MyModule.GUID1.

The merge module ICE reports the second error because the first record in the ModuleComponents table attempts to associate Component1 with the module. This component does not exist in the Component Table of the merge module. A module can only be associated with a component that exists in the module. To fix this, remove the record for the non-existent component.

The merge module ICE reports the third error because the module attempts to add Component3 to the target database. This component has not been associated with the module in the ModuleComponents table. To fix this error, add a record for Component3 to the ModuleComponents table.

See Also

Merge Module ICE Reference


ICEM06

[This is preliminary documentation and subject to change.]

ICEM06 checks for invalid direct references to features by the module.

Merge module ICEs are stored in a merge module .cub file called Mergemod.cub and not in the .cub file containing the ICEs used for package validation.

Result

ICEM06 posts an error when the module database contains direct references to a feature. Feature information must be provided by the user of the module.

Example

ICEM06 posts the following error messages for a module containing the database entries shown below.

The target of shortcut Shortcut1.GUID1 is not a property and not a null GUID.
Modules may not directly reference features.
The row GUID2.LocalServer32.Component2 in the Class table has a feature reference
that is not a null GUID. Modules may not directly reference features.

Shortcut Table (partial)

Shortcut | Target
Shortcut1.GUID1 | cmd.exe
Shortcut2.GUID1 | [MyProp]
Shortcut3.GUID1 | {00000000-0000-0000-0000-000000000000}

Class Table (partial)

CLSID | Context | Component_ | Feature_
GUID1 | LocalServer32 | Component1 | {00000000-0000-0000-0000-000000000000}
GUID2 | LocalServer32 | Component2 | MyFeature

ICEM06 reports the first error because the first record in the Shortcut table has an entry in the Target field that is not a property or a null GUID. A module cannot reference a feature directly. Feature information must be provided by the user of the module. To fix this error, references to a feature should be replaced by a null GUID.

ICEM06 reports the second error because the second record in the Class table has an entry in the Feature field that is not a null GUID. A module cannot reference a feature directly. Feature information must be provided by the user of the module. To fix this error, references to a feature should be replaced by a null GUID.

See Also

Merge Module ICE Reference


ICEM07

[This is preliminary documentation and subject to change.]

ICEM07 verifies that the order of files in the sequence table matches the order of files in MergeModule.CABinet.

Merge module ICEs are stored in a merge module .cub file called Mergemod.cub and not in the .cub file containing the ICEs used for package validation.

Result

ICEM07 posts an error if the order of files in the File table does not match the order in the cabinet file.

Example

IC0M07 would post the following error message for the example shown.

The file 'FileB.GUID1' appears to be out of sequence. It has position 3
in the CAB, but not when the file table is ordered by sequence number.

File Table

File | Sequence
FileA.GUID1 | 1
FileB.GUID1 | 8
FileC.GUID1 | 52

Embedded MergeModule.CABinet

File
FileA.GUID1
FileC.GUID1
FileD.GUID1
FileB.GUID1

Although the file sequence numbers in the file table do not have to be consecutive, and extra files can exist in the cabinet file, the relative sequence of all files in the File table must match the order in MergeModule.CABinet. To fix this error, change the sequence number of FileB to come after FileC to match the file order in the CAB, or rebuild the CAB with the files in the correct order.

See Also

Merge Module ICE Reference


ICEM08

[This is preliminary documentation and subject to change.]

ICEM08 ensures that a module does not exclude another module that it depends on.

Result

ICEM08 posts an error when a module excludes another module that it depends on.

Example

ICEM08 posts the following error message for a module containing the database entries shown in the example.

Error: This module requires module ModuleB.<GUID> (1033v1.0) but also
lists it as an exclusion.

ModuleDependency Table

ModuleID | ModuleLanguage | RequiredID | RequiredLanguage | RequiredVersion
ModuleA.<GUID> | 1033 | ModuleB.<GUID> | 1033 | 1.0

ModuleExclusion Table

ModuleID | ModuleLanguage | ExcludedID | ExcludedLanguage | ExcludedMinVersion | ExcludedMaxVersion
ModuleA.<GUID> | 1033 | ModuleB.<GUID> | 1033 |  | 1.0

To fix the error, remove either the dependency or the exclusion. If ModuleB is a dependency (RequiredID) of ModuleA, you cannot exclude it (as shown in the ExludedID column of the ModuleExclusion table). If you must exclude ModuleB, then you must remove ModuleA's dependency on it.

See Also

Merge Module ICE Reference


ICEM09

[This is preliminary documentation and subject to change.]

ICEM09 verifies the merge module safely handles predefined directories. It does this by verifying that no component in the module installs a directory to a predefined system directory such as "ProgramFilesFolder" or "StartMenuFolder". Instead, modules should use directories with unique names (created with the merge module naming convention) and use custom actions to target the appropriate target directory. This approach prevents modules from conflicting with an existing directory structure in the final database. ICEM09 checks that the custom actions needed for this technique to work either do not exist (so that the merge tool can generate them) or exist in the correct form (so that they work as expected).

Failure to fix a warning or error reported by ICEM09 could cause problems for the clients of your merge module. Directory table rows with primary keys such as ProgramFilesFolder often exist in a database; therefore, if components in your module install directly to predefined directories such as ProgramFilesFolder, the directory entries in the module may collide with already existing rows. This condition would require the user of your module to split the source files from your module in order to match the existing source directory.

Result

ICEM09 reports an error or warning when a module component installs a directory to a pre-defined system directory, causing a possible name conflict with the existing directory structure.

Example

ICEM09 posts the following warnings for a module containing the database entries shown.

Warning: The component 'Component1.<GUID>' installs directly into the pre-defined
directory 'ProgramFilesFolder'. It is recommended that merge modules alias
all such directories to unique names.

Rename the merge module directory so it does not match a Windows Installer property and therefore is unique. Then set a property of the same name to the value of the Windows Installer directory. When directory resolution takes place, the directory has a property of the same name, so the install location of the directory is the value of the property. Files move from the distinct source location to the same target location. This process should completely remove the merge conflicts.

Warning: The 'ModuleInstallExecuteSequence' table contains a type 51 action
(StartMenuFolder.<GUID>) for a pre-defined directory, but this action
does not have sequence number '1'

If the action does not have sequence number 1, it may not merge in to the target database early enough in the sequence to work effectively.

To fix this warning, set the sequence number to 1. Note that most current merge tools (but not some older versions) will generate these custom actions at merge time, so it is not always necessary to explicitly author the actions into the merge module.

Warning: The 'CustomAction' table contains a type 51 action (MyAppDataFolderAction)
for a pre-defined directory, but the name is not the same as the target directory.
Many merge tools will generate duplicate actions."

Because the CustomAction column is the primary key of CustomAction table, some merge tools may generate duplicate actions because the pre-authored action name is different.

To fix this warning, name the action the same as the target directory. Note that most current merge tools (but not some older versions) generate these custom actions at merge time, so it is not always necessary to explicitly author the actions into the merge module.

Directory Table

Directory | Directory_Parent | DefaultDir
ProgramFilesFolder | Directory1 | A
StartMenuFolder | Directory2 | B:C
AppDataFolder | Directory3 | D
MyPicturesFolder | Directory4 | E

Component Table

Component | Directory
Component1.<GUID> | ProgramFilesFolder
Component2.<GUID> | StartMenuFolder
Component3.<GUID> | AppDataFolder
Component4.<GUID> | MyPicturesFolder

CustomAction Table

CustomAction | Type | Source | Target
StartMenuFolder.<GUID> | 51 | StartMenuFolder.<GUID> | [StartMenuFolder]
MyAppDataFolderAction | 51 | AppDataFolder.<GUID> | [AppDataFolder]

ModuleInstallExecuteSequence Table

Action | Sequence | BaseAction | After | Condition
StartMenuFolder.<GUID> | 100 |  |  |

See Also

Merge Module ICE Reference


ICEM10

[This is preliminary documentation and subject to change.]

ICEM10 verifies that a merge module does not contain disallowed properties in the Property Table. The disallowed properties are the ProductLanguage, ProductCode, ProductVersion, ProductName, and Manufacturer properties, which are product specific.

Result

ICEM10 Posts an error when a merge module contains a disallowed property in the Property Table.

Example

ICEM10 posts the following error messages for a module containing the database entries shown below.

The property 'ProductLanguage' is not allowed in a merge module.

The property 'Manufacturer' is not allowed in a merge module.

Property Table (partial)

Property | Values
Color | Red
Manufacturer | Microsoft
ProductLanguage | 1033

To fix the errors, perform the following:

  1. Remove the 'Manufacturer' property from the Property table.
  2. Remove the 'ProductLangauge' property from the Property table.

Table Used During Execution

Property Table

See Also

Merge Module ICE Reference


ICEM11

[This is preliminary documentation and subject to change.]

ICEM11 verifies that a Configurable Merge Module lists the ModuleConfiguration table and ModuleSubstitution table in the ModuleIgnoreTable table of the module. This ensures that merge tools that do not recognize configurable merge modules(less than version 1.5) do not copy these tables into the target database.

This ICEM is available in the Mergemod.cub file provided in the Windows Installer 1.5 SDK and later. For details, see Platform SDK Components for Windows Installer Developers.

Result

ICEM11 posts an error if the module contains a ModuleConfiguration or ModuleSubstitution table not listed in the ModuleIgnoreTable table.

Example

ICEM11 posts the following error messages for a module containing the database entries shown below.

Error The module contains a ModuleConfiguration or ModuleSubstitution
table. These tables must be listed in the ModuleIgnoreTable table.

ModuleConfiguration (partial)

Name | Format | Type | ContextData | DefaultValue
IconKey1 | 1 | Binary | Icon | DefaultIcon

ModuleSubstitution

Table | Row | Column | Value
Control | Dialog1;Control1 | Text | [IconKey1]

ModuleIgnoreTable

Table
ModuleConfiguration

To fix this error include both the ModuleSubstitution and ModuleConfiguration tables in the ModuleIgnoreTable table.

Table Used During Execution

ModuleSubstitution

ModuleConfiguration

ModuleIgnoreTable

See Also

Merge Module ICE Reference


ICEM12

[This is preliminary documentation and subject to change.]

ICEM12 verifies that in a ModuleSequence table, standard actions have Sequence numbers and custom actions have BaseAction and After values.

This ICEM is available in the Mergemod.cub file provided in the Windows Installer 1.5 SDK and later. For details, see Platform SDK Components for Windows Installer Developers.

Result

ICEM12 posts an error in the following cases:

  • It finds the module contains a standard action without a sequence number.
  • It finds that a standard action has values entered in the BaseAction or After fields of the ModuleAdminUISequence table, ModuleAdminExecuteSequence table, ModuleAdvtExecuteSequence table, ModuleInstallUISequence table, or ModuleInstallExecuteSequence table.
  • It finds the module contains a custom action without any values entered into the Sequence, BaseAction or After fields of the ModuleAdminUISequence table, ModuleAdminExecuteSequence table, ModuleAdvtExecuteSequence table, ModuleInstallUISequence table, or ModuleInstallExecuteSequence table.

ICEM12 posts a warning if it finds a custom action that has a Sequence number specified, but no value in the BaseAction or After fields.

Note that all actions found in the CustomAction table are considered custom actions. All other action are considered standard actions.

Example

ICEM12 posts the following error and warning messages for a module containing the database entries shown below:

Since the action `Action1` in ModuleInstallExecuteSequence table is a
custom action, it is recommended that it does not have sequence number
but has BaseAction/After values instead.

Since the action `Action3` in ModuleAdminExecuteSequence table is a
custom action, the Sequence field and the BaseAction/After fields can
not both be null.

Since the action `Action2` in ModuleAdminExecuteSequence table is a
standard action, the BaseAction and After fields must be null.

Since the action `Action2` in ModuleAdminExecuteSequence table is a
standard action, the Sequence field can not be null.

CustomAction

Action | Type | Source | Target
Action1 | 30 | source1 | target1
Action3 | 30 | source3 | target3

ModuleAdminExecuteSequence

Action | Sequence | BaseAction | After | Condition
Action2 |  | Action1 | 1 | true
Action3 |  |  |  | true

ModuleInstallExecuteSequence

Action | Sequence | BaseAction | After | Condition
Action1 | 1 |  |  | true

To fix these errors try the following:

  • Remove the sequence number for the custom action Action1 and use the BaseAction and After fields instead.
  • Enter values into the Sequence, BaseAction, or After fields for the custom action Action3. Leave the BaseAction and After fields empty for standard action Action2.
  • Do not leave the Sequence field empty for standard action Action2.

See Also

Merge Module ICE Reference


Windows Installer Examples

The following sections present an example of authoring installation package for an application. An example of a minimal user interface for this sample is provided in the Platform SDK Components for Windows Installer Developers as the file Uisample.msi. If you have the SDK, you have access to all the tools and data necessary to reproduce this sample installation package and user interface. For detailed examples, see:

An Installation Example

An Upgrade Example

A Customization Transform Example

A Small Update Patching Example

A Localization Example

A URL Based Windows Installer Installation Example


An Installation Example

This example illustrates how to create a simple Windows Installer package that installs an application. The sample installs Notepad, a text editor included with the Microsoft® Windows® and Windows NT® operating systems, and several text files describing events and admissions at the imaginary Red Park Arena.

The sample has the following specifications:

  • The application is provided to users as a self-installing Windows Installer package that installs all the required files, shortcuts, and registry information.
  • The installation package may present a UI wizard to the user during setup to collect user information.
  • During setup, users have the option of selecting individual features to be installed to run-locally, to run-from-source, or to not be installed.
  • One of the features can be presented to users as an install-on-demand feature.
  • The same package uninstalls the application and removes all the application files and registry information from the user's computer.
  • The package is prepared to receive a major upgrade that includes changing its product code.

To reproduce the example, you need a software tool capable of creating and editing a blank Windows Installer database. Several package creation tools are available from independent software vendors. A Windows Installer database editor called Orca is provided in the Platform SDK Components for Windows Installer Developers.

To complete the example, follow these steps:

Planning the Installation

Importing a Blank Database

Specifying Directory Structure

Specifying Components

Specifying Files and File Attributes

Specifying Source Media

Specifying Features

Specifying Feature-Component Relationships

Adding Registry Information

Specifying Shortcuts

Specifying Properties

Importing the InstallExecuteSequence

Importing the InstallUISequence

Importing the AdminExecuteSequence

Importing the AdminUISequence

Importing the AdvtExecuteSequence

Adding Summary Information

Importing the User Interface

Validating an Installation Database


Planning the Installation

When the installation of an existing application is moved to the Windows Installer from another setup technology, the setup developer may start authoring a Windows Installer package using the source and target file images of the existing installation. A detailed plan of how the files and other resources are organized at the source and target is also a good starting point for developing a package for a new application.

The sample installation package takes the following files that are stored at the source location for the application and installs them to the target on the user's computer.

File | Description | Path to source | Path to target
Redpark.exe | Text editor executable file. | C:\Sample\Notepad\Redpark.exe | [ProgramFilesFolder]\Red_Park\Redpark.exe
Readme.txt | An informational file. | C:\Sample\Notepad\Readme.txt | [ProgramFilesFolder]\Red_Park\Readme.txt
Help.txt | Help manual | C:\Sample\Notepad\Help.txt | Not installed. Always run-from-source.
Baseball.txt | Baseball game schedule for year 2000. | C:\Sample\Notepad\Events\Baseball.txt | [ProgramFilesFolder]\Red_Park\Sports\Baseball.txt
Football.txt | Football game schedule for year 2000. | C:\Sample\Notepad\Events\Football.txt | [ProgramFilesFolder]\Red_Park\Sports\Football.txt
Dance.txt | Dance performances for year 2000. | C:\Sample\Notepad\Events\Dance.txt | [ProgramFilesFolder]\Red_Park\Arts\Dance.txt
Concert.txt | Music performances for year 2000. | C:\Sample\Notepad\Events\Concert.txt | [ProgramFilesFolder]\Red_Park\Arts\Concert.txt
January.txt | Admissions in January of year 2000. | C:\Sample\Notepad\Gate\January.txt | [ProgramFilesFolder]\Red_Park\Gate\January.txt
NewYears.txt | Admissions on New Years Day of year 2000. | C:\Sample\Notepad\Gate\Holidays\NewYears.txt | [ProgramFilesFolder]\Red_Park\Gate\NewYears.txt

The sample also writes the following values in the user's registry under HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Notepad Sample.

Name | Value
lfCharSet | 0
lfClipPrecision | 2
lfFaceName | FixedSys
lfItalic | 0
lfOrientation | 0
lfOutPrecision | 1
fSavePageSetting | 0
lfPitchAndFamily | 49
iPointSize | 120
lfQuality | 2
lfStrikeOut | 0
lfWeight | 400
fWrap | 0

The sample also installs the following shortcuts. One of these shortcuts may be selected during setup as an advertised shortcut so that the user can install-on-demand the Baseball feature.

Name | Shortcut location | Shortcut target
sNotepad | [ProgramFilesFolder]\Red_Park\Menu\ | [ProgramFilesFolder]\Red_Park\Redpark.exe
sReadme | [ProgramFilesFolder]\Red_Park\Menu\ | [ProgramFilesFolder]\Red_Park\Readme.txt
sHelp | [ProgramFilesFolder]\Red_Park\Menu\ | [ProgramFilesFolder]\Sample\Notepad\Help.txt
sBaseball | [ProgramFilesFolder]\Red_Park\Menu\ | [ProgramFilesFolder]\Red_Park\Sports\Baseball.txt
sFootball | [ProgramFilesFolder]\Red_Park\Menu\ | [ProgramFilesFolder]\Red_Park\Sports\Football.txt
sDance | [ProgramFilesFolder]\Red_Park\Menu\ | [ProgramFilesFolder]\Red_Park\Arts\Dance.txt
sConcert | [ProgramFilesFolder]\Red_Park\Menu\ | [ProgramFilesFolder]\Red_Park\Arts\Concert.txt
sJanuary | [ProgramFilesFolder]\Red_Park\Menu\ | [ProgramFilesFolder]\Red_Park\Gate\January.txt
sNewYears | [ProgramFilesFolder]\Red_Park\Menu\ | [ProgramFilesFolder]\Red_Park\Gate\NewYears.txt

To reproduce the sample, begin by creating the source directory structure given in the first table. You can make a copy of your system's Notepad.exe file and then rename this copy Redpark.exe. Use the Notepad editor to create the remaining text files. The directory structure of the target, the registry values, and the shortcuts are added by authoring the installation database.

Continue


Importing a Blank Database

To reproduce the sample you need to copy, or create with a software tool, a Windows Installer database file. A totally blank installation database, Schema.msi, is provided with the Platform SDK Components for Windows Installer Developers. The SDK also provides a partially blank database, uisample.msi, that contains the suggested sequence tables and data required for a simple user interface. Make a copy of uisample.msi and move it into the same directory containing the Notepad folder you created in Planning the Installation. Rename the file MNP2000.msi. The installation database file and the source files must both be located at the root of the same directory. For example:

C:\Sample\MNP2000.msi

C:\Sample\Notepad\

If you do not use Uisample.msi, then you must obtain a blank database, such as Schema.msi, and enter information for the installation using a database editing tool such as Orca, which is provided with the SDK, or another database editor.

Continue


Specifying Directory Structure

The installer keeps information about the installation directory structure in the Directory Table. See the Core Tables Group. In this section you add directory structure information for the Notepad sample to the empty database you created in Importing a Blank Database. Use the database editor Orca that is provided with the SDK, or another editor, to open the Directory Table in MNP2000.msi. Use the editor to enter the following data into the blank Directory table.

Directory Table

Directory | Directory_Parent | DefaultDir
TARGETDIR |  | SourceDir
ProgramFilesFolder | TARGETDIR | .
ARTSDIR | NOTEPADDIR | Arts:Events
HOLDIR | MONDIR | .:Holidays
MENUDIR | NOTEPADDIR | Menu
MONDIR | NOTEPADDIR | Gate
NOTEPADDIR | ProgramFilesFolder | Red_Park:Notepad
SPORTDIR | NOTEPADDIR | Sports:Events

Entering this data into the Directory table specifies the source and target directory structures. See the Directory Table and Using the Directory Table topics. Note that the TARGETDIR property must be the name of one root in the Directory table of every installation. See also Using the Directory Table.

Continue


Specifying Components

The installer installs and removes blocks of resources referred to as Windows Installer Components. See the Core Tables Group and Components and Features in the Windows Installer overview. In this section you add information about the components used by the Notepad example to the Component Table you created in Importing a Blank Database. See Organizing Applications into Components and Defining Installer Components for a discussion of the rules that control the definition of new components.

The Notepad sample uses eight components to control resources.

Component | Resources
Baseball | Baseball.txt, sBaseball
Concert | Concert.txt, sConcert
Dance | Dance.txt, sDance
Football | Football.txt, sFootball
Help | Help.txt, sHelp
January | January.txt, sJanuary
NewYears | NewYears.txt, sNotepad
Notepad | Redpark.exe, Readme.txt, sReadme, sNotepad, HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Notepad Sample

Every component should be identified with a unique component ID GUID. If you are reproducing the sample, do not reuse the same component ID GUIDs in the following table. Instead use a utility such as Guidgen.exe to generate new GUIDs for your components. Be sure that you use a GUID string consistent with the Windows Installer GUID data type. For a discussion of when to define a new component by specifying a new component code, see the following topics:

  • Changing the Component Code
  • What happens if the component rules are broken?

Use Orca or another database editor to enter the following data into the blank Component table of MNP2000.msi. Do not reuse the GUIDs shown below in the ComponentId column in your sample.

Component Table

Component | ComponentId | Directory_ | Attributes | Condition | Keypath
Baseball | {F54ABAC0-33F2-11D3-91D7-00C04FD70856} | SPORTDIR | 2 |  | Baseball.txt
Concert | {76FA7A80-33F6-11D3-91D8-00C04FD70856} | ARTSDIR | 2 |  | Concert.txt
Dance | {CCF834A1-33F8-11D3-91D8-00C04FD70856} | ARTSDIR | 2 |  | Dance.txt
Football | {CCF834A0-33F8-11D3-91D8-00C04FD70856} | SPORTDIR | 2 |  | Football.txt
Help | {AD10EB50-33C1-11D3-91D6-00C04FD70856} | NOTEPADDIR | 2 |  | Help.txt
January | {CF0BC690-33C9-11D3-91D6-00C04FD70856} | MONDIR | 2 |  | January.txt
NewYears | {A42D9140-33D8-11D3-91D6-00C04FD70856} | HOLDIR | 2 |  | NewYears.txt
Notepad | {19BED232-30AB-11D3-91D3-00C04FD70856} | NOTEPADDIR | 2 |  | Redpark.exe

The source and target directories for each component is specified by the value entered into the Directory_ column. The installer resolves the location of this directory using the information in the Directory Table. The installer uses the key path files specified in the KeyPath column to detect each component. The remote execution attributes are set in the sample so that the components can be run-from-source or run-locally.

Continue


Specifying Files and File Attributes

The installation and removal of each file is determined by the Windows Installer Component that controls the file. Once the grouping of resources into components has been specified, file attribute information can be added to the installation database.In this section, you add file information to the installation database for the Notepad sample. See the File Tables Group.

The files in the Notepad sample are uncompressed. See Compressed and Uncompressed Sources for information on how to add cabinet files to packages. This sample does not contain file versioning information. For more information about file versioning, see File Versioning Rules and Default File Versioning.

Use your database editor to open MNP2000.msi and enter the following data into the empty File Table.

File Table

File | Component_ | FileName | FileSize | Version | Language | Attributes | Sequence
Baseball.txt | Baseball | Baseball.txt | 1000 |  |  | 0 | 1
Concert.txt | Concert | Concert.txt | 1000 |  |  | 0 | 1
Dance.txt | Dance | Dance.txt | 1000 |  |  | 0 | 1
Football.txt | Football | Football.txt | 1000 |  |  | 0 | 1
Help.txt | Help | Help.txt | 1000 |  |  | 0 | 1
January.txt | January | January.txt | 1000 |  |  | 0 | 1
NewYears.txt | NewYears | NewYears.txt | 1000 |  |  | 0 | 1
Redpark.exe | Notepad | Redpark.exe | 45328 |  |  | 0 | 1
Readme.txt | Notepad | Readme.txt | 1000 |  |  | 0 | 1

Continue


Specifying Source Media

The Media table describes the set of disks that make up the source media for the installation. See the File Tables Group. In this section, you add information about the source media for the Notepad sample.

Use your database editor to open MNP2000.msi and enter the following data into the empty Media Table.

Media Table

DiskId | LastSequence | DiskPrompt | Cabinet | VolumeLabel | Source
1 | 1 |  |  |  |

Continue


Specifying Features

The installer enables users to install and remove blocks of an application's functionality referred to as Windows Installer Features. See the Core Tables Group and Components and Features in the Windows Installer overview. In this section you add information to the installation database about the features that are available for the Notepad sample.

The Notepad sample installs the following feature in a hierarchy of parent and child features. In the following list, child features are indented relative to their parent feature. The features should display in this order in the SelectionTree Control of the user interface.

Notepad

Readme

Help

Gate

January

NewYears

Sport

Baseball

Football

Arts

Concert

Dance

Use your database editor to open MNP2000.msi and enter the following data into the empty Feature Table.

Feature Table

Feature | Feature_Parent | Title | Description | Display | Level | Directory_ | Attributes
Arts |  | Arts | Arts events at Red Park. | 20 | 3 | NOTEPADDIR | 0
Baseball | Sport | Baseball | Baseball Games | 17 | 3 | SPORTDIR | 32
Concert | Arts | Concert | Concert events at Red Park | 21 | 3 | ARTSDIR | 2
Dance | Arts | Dance | Dance events at Red Park | 23 | 3 | ARTSDIR | 2
Football | Sport | Football | Football Games | 19 | 3 | SPORTDIR | 2
Gate |  | Gate | Red Park's Admissions | 6 | 3 | NOTEPADDIR | 0
Help | Notepad | Help | Help file. | 5 | 3 | NOTEPADDIR | 1
January | Gate | January | January Admissions | 10 | 3 | MONDIR | 2
NewYears | January | New Years Day | New Years Day Admissions | 11 | 3 | HOLDIR | 2
Notepad |  | Notepad | Notepad Editor | 1 | 3 | NOTEPADDIR | 0
Readme | Notepad | Readme | Readme File | 3 | 3 | NOTEPADDIR | 0
Sport |  | Sport Events | Sport Events at Red Park | 14 | 3 | NOTEPADDIR | 0

Continue


Specifying Feature-Component Relationships

Each Windows Installer Feature uses one or more Windows Installer Components, and features may share components. The FeatureComponents table defines the relationship between features and components. See the Core Tables Group and Components and Features in the Windows Installer overview. In this section you add information to the FeatureComponents table of the Notepad sample.

Use your database editor to open MNP2000.msi and enter the following data into the empty FeatureComponents Table.

FeatureComponents Table

Feature_ | Component_
Baseball | Baseball
Concert | Concert
Dance | Dance
Football | Football
Help | Help
January | January
NewYears | NewYears
Notepad | Notepad
Readme | Notepad

Continue


Adding Registry Information

The Registry table, and related tables, of the installation database holds the registry information the application needs written in the system registry. See the Registry Tables Group. In this section you add the information that is to be registered on the user's computer by the Notepad sample.

Use your database editor to open MNP2000.msi and enter the following data into the empty Registry Table.

Registry Table

Registry | Root | Key | Name | Value | Component_
CharSet | 2 | SOFTWARE\Microsoft\Notepad Sample | lfCharSet | #0 | Notepad
ClipPrecision | 2 | SOFTWARE\Microsoft\Notepad Sample | lfClipPrecision | #2 | Notepad
Escapement | 2 | SOFTWARE\Microsoft\Notepad Sample | lfFaceName | FixedSys | Notepad
Italic | 2 | SOFTWARE\Microsoft\Notepad Sample | lfItalic | #0 | Notepad
Orientation | 2 | SOFTWARE\Microsoft\Notepad Sample | lfOrientation | #0 | Notepad
OutPrecision | 2 | SOFTWARE\Microsoft\Notepad Sample | lfOutPrecision | #1 | Notepad
PageSettings | 2 | SOFTWARE\Microsoft\Notepad\Sample | fSavePageSetting | #0 | Notepad
PitchAndFamily | 2 | SOFTWARE\Microsoft\Notepad Sample | lfPitchAndFamily | #49 | Notepad
PointSize | 2 | SOFTWARE\Microsoft\Notepad Sample | iPointSize | #120 | Notepad
Quality | 2 | SOFTWARE\Microsoft\Notepad Sample | lfQuality | #2 | Notepad
StrikeOut | 2 | SOFTWARE\Microsoft\Notepad Sample | lfStrikeOut | #0 | Notepad
Weight | 2 | SOFTWARE\Microsoft\Notepad Sample | lfWeight | #400 | Notepad
Wrap | 2 | SOFTWARE\Microsoft\Notepad Sample | fWrap | #0 | Notepad

Continue


Specifying Shortcuts

The Shortcut table and related tables of the installation database hold information needed to install shortcuts. See the Program Information Tables Group and Editing Installer Shortcuts.

In this section you add information that specifies advertised and non-advertised shortcuts for the Notepad sample.

Use your database editor to open MNP2000.msi and enter the following data into the Shortcut Table.

Shortcut Table

Shortcut | Directory_ | Name | Component_ | Target | Arguments | Description | Hotkey | Icon_ | IconIndex | ShowCmd | WkDir
sBaseball | MENUDIR | Baseball.txt | Baseball | Baseball |  |  |  | orca_icon.exe |  |  |
sConcert | MENUDIR | Concert.txt | Concert | [#Concert.txt] |  |  |  |  |  |  |
sDance | MENUDIR | Dance.txt | Dance | [#Dance.txt] |  |  |  |  |  |  |
sFootball | MENUDIR | Football.txt | Football | [#Football.txt] |  |  |  |  |  |  |
sHelp | MENUDIR | Help.txt | Help | [#Help.txt] |  |  |  |  |  |  |
sJanuary | MENUDIR | January.txt | January | [#January.txt] |  |  |  |  |  |  |
sNewYears | MENUDIR | NewYears.txt | NewYears | [#NewYears.txt] |  |  |  |  |  |  |
sNotepad | MENUDIR | Redpark.exe | Notepad | [#Redpark.exe] |  |  |  |  |  |  |
sReadme | MENUDIR | Readme.txt | Notepad | [#Readme.txt] |  |  |  |  |  |  |

The sample installation needs to enable installation of an advertised shortcut for the Baseball feature. This requires specifying a key to the Icon table in the Icon_ column of the Shortcut table. For the purposes of this example you may copy the icon for the Orca database editor provided with the Windows Installer SDK. Export the Icon table from Orca.msi and then merge this table into the MNP2000.msi database using Orca or another merge tool. Orca also creates a directory named Icon in the directory containing MNP2000.msi, and adds the icon binary data file orca_icon.exe.ibd. See the Data column in Icon table. The completed Icon Table should look as follows when viewed in Orca.

Icon Table

Name | Data
orca_icon.exe | [Binary Data]

Continue


Specifying Properties

Windows Installer properties are global variables the installer uses during an installation. See the sections under Properties. If in the section Importing a Blank Database you used uisample.msi from the Windows Installer SDK, the Property Table in your copy of MNP2000.msi already contains many properties that are used by the user interface. In this section you add additional information to the Property table specific to the installation of the Notepad sample. See also the Program Information Tables Group.

There are five properties that are required in every installation package, and these must be updated for the Notepad sample in the Property table of MNP2000.msi:

  • ProductCode
  • ProductLanguage
  • Manufacturer
  • ProductVersion
  • ProductName

Although not required by all installation packages, applications that may in the future receive an upgrade should also have an UpgradeCode property. See Preparing an Application for Future Major Upgrades.

Use your database editor to open MNP2000.msi and enter the following data into the Property Table. The list provides links to the reference topics for built-in installer properties. The property names that are not links are author-defined properties. Many of the properties imported from uisample.msi are for the sample user interface. The later section User Interface for the Installation Sample discusses the user interface.

Property Table

Property | Value
ARPHELPLINK | http://www.microsoft.com/management
BannerBitmap | bannrbmp
ButtonText_Back | < &Back
ButtonText_Browse | Br&owse
ButtonText_Cancel | Cancel
ButtonText_Exit | &Exit
ButtonText_Finish | &Finish
ButtonText_Ignore | &Ignore
ButtonText_Install | &Install
ButtonText_Next | &Next >
ButtonText_No | &No
ButtonText_OK | OK
ButtonText_Remove | &Remove
ButtonText_Reset | &Reset
ButtonText_Resume | &Resume
ButtonText_Retry | &Retry
ButtonText_Return | &Return
ButtonText_Yes | &Yes
CompleteSetupIcon | completi
ComponentDownload | ftp://anonymous@microsoft.com/components/
CustomSetupIcon | custicon
DefaultUIFont | DlgFont8
DialogBitmap | dlgbmp
DlgTitleFont | {&DlgFontBold8}
ErrorDialog | ErrorDlg
ExclamationIcon | exclamic
False | 0
Iagree | No
InfoIcon | info
InstallerIcon | insticon
INSTALLLEVEL | 3
InstallMode | Typical
Manufacturer | Microsoft
PIDTemplate | 12345<###-%%%%%%%>@@@@@
ProductCode | {18A9233C-0B34-4127-A966-C257386270BC}
ProductID | none
ProductLanguage | 1033
ProductName | MNP2000
ProductVersion | 01.40.0000
Progress1 | Installing
Progress2 | installs
PROMPTROLLBACKCOST | P
RemoveIcon | removico
RepairIcon | repairic
Setup | Setup
True | 1
UpgradeCode | {908E378A-9551-4772-BF1D-5CFAF6FD9CB4}
Wizard | Setup Wizard

Continue


Importing the InstallExecuteSequence

The InstallExecuteSequence table lists the actions that are executed when the installer executes the top-level INSTALL action. See Installation Procedure Tables Group, Using a Sequence Table, and the Sequence Table Detailed Example.

If in the section Importing a Blank Database you used uisample.msi from the Windows Installer SDK, the sequence tables in your copy of MNP2000.msi already contains the suggested action sequences described in Using a Sequence Table. No changes to these sequences are necessary to author the Notepad installation package.

Use your database editor to open MNP2000.msi and enter the following data into the InstallExecuteSequence table.

InstallExecuteSequence Table

Action | Condition | Sequence
AllocateRegistrySpace | NOT Installed | 1550
AppSearch |  | 400
BindImage |  | 4300
CCPSearch | NOT Installed | 500
CostFinalize |  | 1000
CostInitialize |  | 800
CreateFolders |  | 3700
CreateShortcuts |  | 4500
DeleteServices | VersionNT | 2000
DuplicateFiles |  | 4210
FileCost |  | 900
InstallFiles |  | 4000
InstallFinalize |  | 6600
InstallInitialize |  | 1500
InstallODBC |  | 5400
InstallServices | VersionNT | 5800
InstallValidate |  | 1400
LaunchConditions |  | 100
MoveFiles |  | 3800
PatchFiles |  | 4090
ProcessComponents |  | 1600
PublishComponents |  | 6200
PublishFeatures |  | 6300
PublishProduct |  | 6400
RegisterClassInfo |  | 4600
RegisterComPlus |  | 5700
RegisterExtensionInfo |  | 4700
RegisterFonts |  | 5300
RegisterMIMEInfo |  | 4900
RegisterProduct |  | 6100
RegisterProgIdInfo |  | 4800
RegisterTypeLibraries |  | 5500
RegisterUser |  | 6000
RemoveDuplicateFiles |  | 3400
RemoveEnvironmentStrings |  | 3300
RemoveFiles |  | 3500
RemoveFolders |  | 3600
RemoveIniValues |  | 3100
RemoveODBC |  | 2400
RemoveRegistryValues |  | 2600
RemoveShortcuts |  | 3200
RMCCPSearch | NOT Installed | 600
SelfRegModules |  | 5600
SelfUnregModules |  | 2200
SetODBCFolders |  | 1100
StartServices | VersionNT | 5900
StopServices | VersionNT | 1900
UnpublishComponents |  | 1700
UnpublishFeatures |  | 1800
UnregisterClassInfo |  | 2700
UnregisterComPlus |  | 2100
UnregisterExtensionInfo |  | 2800
UnregisterFonts |  | 2500
UnregisterMIMEInfo |  | 3000
UnregisterProgIdInfo |  | 2900
UnregisterTypeLibraries |  | 2300
ValidateProductID |  | 700
WriteEnvironmentStrings |  | 5200
WriteIniValues |  | 5100
WriteRegistryValues |  | 5000
RemoveExistingProducts |  | 6700
MigrateFeatureStates |  | 1200
FindRelatedProducts |  | 200

Continue


Importing the InstallUISequence

The InstallUISequence table lists actions that are executed when the top-level INSTALL action is executed and the internal user interface level is set to full UI or reduced UI. The installer skips the actions in this table if the user interface level is set to basic UI or to no UI. See User Interface and User Interface Levels. See Installation Procedure Tables Group, Using a Sequence Table, and the Sequence Table Detailed Example.

If in the section Importing a Blank Database you used uisample.msi from the Windows Installer SDK, the sequence tables in your copy of MNP2000.msi already contains the suggested action sequences described in Using a Sequence Table. No changes to these sequences should be necessary to author the Notepad installation package.

Use your database editor to open MNP2000.msi and enter the following data into the InstallUISequence table.

InstallUISequence Table

Action | Condition | Sequence
AppSearch |  | 400
CCPSearch | NOT Installed | 500
CostFinalize |  | 1000
CostInitialize |  | 800
ExecuteAction |  | 1300
ExitDlg |  | -1
FatalErrorDlg |  | -3
FileCost |  | 900
LaunchConditions |  | 100
MaintenanceWelcomeDlg | Installed AND NOT RESUME AND NOT Preselected | 1250
PrepareDlg |  | 140
ProgressDlg |  | 1280
ResumeDlg | Installed AND (RESUME OR Preselected) | 1240
RMCCPSearch | NOT Installed | 600
UserExitDlg |  | -2
WelcomeDlg | NOT Installed | 1230
MigrateFeatureStates |  | 1200
FindRelatedProducts |  | 200

Continue


Importing the AdminExecuteSequence

The AdminExecuteSequence table lists actions that the installer executes when it calls the top-level ADMIN action. See Installation Procedure Tables Group, Using a Sequence Table, and the Sequence Table Detailed Example.

If in the section Importing a Blank Database you used uisample.msi from the Windows Installer SDK, the sequence tables in your copy of MNP2000.msi already contains the suggested action sequences described in Using a Sequence Table. No changes to these sequences should be necessary to author the Notepad sample installation package.

Use your database editor to open MNP2000.msi and enter the following data into the AdminExecuteSequence table.

AdminExecuteSequence Table

Action | Condition | Sequence
CostFinalize |  | 1000
CostInitialize |  | 800
FileCost |  | 900
InstallAdminPackage |  | 3900
InstallFiles |  | 4000
InstallFinalize |  | 6600
InstallInitialize |  | 1500
InstallValidate |  | 1400

Continue


Importing the AdminUISequence

The AdminUISequence table lists actions that the installer calls when it executes the top-level ADMIN action and the internal user interface level is set to full UI or reduced UI. The installer skips the actions in this table if the user interface level is set to basic UI or no UI. See User Interface and User Interface Levels. See Installation Procedure Tables Group, Using a Sequence Table, and the Sequence Table Detailed Example.

If in the section Importing a Blank Database you used uisample.msi from the Windows Installer SDK, the sequence tables in your copy of MNP2000.msi already contains the suggested action sequences described in Using a Sequence Table. No changes to these sequences should be necessary to install the Notepad sample.

Use your database editor to open MNP2000.msi and enter the following data into the AdminExecuteSequence table.

AdminUISequence Table

Action | Condition | Sequence
AdminWelcomeDlg |  | 1230
CostFinalize |  | 1000
CostInitialize |  | 800
ExecuteAction |  | 1300
ExitDlg |  | -1
FatalErrorDlg |  | -3
FileCost |  | 900
PrepareDlg |  | 140
ProgressDlg |  | 1280
UserExitDlg |  | -2

Continue


Importing the AdvtExecuteSequence

The AdvtExecuteSequence table lists actions the installer calls when it executes the top-level ADVERTISE action. See Installation Procedure Tables Group, Using a Sequence Table, and the Sequence Table Detailed Example.

If in the section Importing a Blank Database you used uisample.msi from the Windows Installer SDK, the sequence tables in your copy of MNP2000.msi already contains the suggested action sequences described in Using a Sequence table. No changes to these sequences should be necessary to author the Notepad sample installation package.

Use your database editor to open MNP2000.msi and enter the following data into the AdminExecuteSequence table.

AdvtExecuteSequence Table

Action | Condition | Sequence
CostFinalize |  | 1000
CostInitialize |  | 800
CreateShortcuts |  | 4500
InstallFinalize |  | 6600
InstallInitialize |  | 1500
InstallValidate |  | 1400
PublishComponents |  | 6200
PublishFeatures |  | 6300
PublishProduct |  | 6400
RegisterClassInfo |  | 4600
RegisterExtensionInfo |  | 4700
RegisterMIMEInfo |  | 4900
RegisterProgIdInfo |  | 4800

The AdvtUISequence table is not used by the installer. This table should not exist or be left empty in the installation database.

Continue


Adding Summary Information

The following summary information properties must be defined in every installation package, using a software tool to access the Istream interface of the Summary Information Stream. For example, you can use the tool Msiinfo.exe provided with the Windows Installer SDK to set these properties. If these properties are not set, the package will not pass Package Validation.

Summary information property | Data | Notes
Template (Platform and Language) | ;1033 | Platform and language used by the database. Leaving the platform field empty indicates the package is platform independent. The ProductLanguage property from the database is typically used for this summary property. The sample's Language ID indicates that the package uses U.S. English.
Revision Number (Package Code) | {4966AEC4-3C59-4B07-9B98-1B6A7103C0D3} | This is the package code GUID that uniquely identifies the sample package. If you reproduce this sample, use a utility such as GUIDGEN to generate a different GUID for your package. The results of GUIDGEN contain lowercase characters, note that you must change all lowercase characters to uppercase for a valid package code. See Package Codes.
Page Count (Minimum Installer Version) | 110 | For Windows Installer version 1.0, this property should be set to the integer 100. For Windows Installer version 1.1, this property should be set to the integer 110.
Word Count (Type of Source) | 0 | The global source type for the package is long file names and uncompressed. See Compressed and Uncompressed Sources and the description of the Attributes column of the File table for more information.

The remaining summary information stream properties are not required, but should be set for the MNP2000.msi sample.

Summary information property | Data | Notes
Title | Installation Database | Informs users that this database is for an installation rather than a transform or a patch.
Subject | MNP2000 | File browsers can display this as the product to be installed with this database.
Keywords | Installer, MSI, Database | File browsers that are capable of keyword searching can search for these words.
Author | Microsoft Corporation | Name of the product's manufacturer.
Comments | This installer database contains the logic and data required to install Notepad. | Informs users about the purpose of this database.
Creating Application | Orca | Application used to create the installation database. The sample specifies the Orca database editor as an example.
Security | 0 | The sample database is unrestricted read-write.

You do not need the set the Last Saved By, Last Saved Time/Date, Create Time/Date, Last Printed, Character Count, and Codepage summary properties to complete this sample database. The sample relies upon the database editing tool to set and update these optional properties.

For example, to use MsiInfo to add the summary information to the sample, change to the directory containing the database Notepad.msi and use the following command line. Do not reuse the example package ID shown below.

Msiinfo.exe Notepad.msi -T "Installation Database" -J Subject -A "Microsoft Corporation" -K "Installer, MSI, Database" -O "This installer database contains the logic and data required to install Notepad." -P ;1033 -V {4966AEC4-3C59-4B07-9B98-1B6A7103C0D3} -G 100 -W 0 -N Orca -U 0

For more details about summary information, see About the Summary Information Stream, Using the Summary Information Stream, and Summary Information Stream Reference.

See the Summary Information Stream Property Set for a complete list of all the summary information properties and Summary Property Descriptions for their description.

Continue


Importing the User Interface

In addition to information discussed in previous sections, uisample.msi also contains data for a sample user interface. If you merged uisample.msi into MNP2000.msi in the section Importing a Blank Database, then this information is present in MNP2000.msi as well. The information for the sample user interface is in the following tables.

ActionText table

Binary table

Control table

ControlEvent table

Dialog table

Error table

EventMapping table

RadioButton table

TextStyle table

UIText table

The database editor Orca provided with the Windows installer includes a dialog preview option that you can use to preview the dialogs of the user interface that is specified by the data in the above tables.

The sample installation package MNP2000.msi is now ready for package validation. Always run validation on a new package before attempting to install the package for the first time. This is discussed in Validating the Installation Sample.

If you do not want to include the user interface in the sample package, omit or remove the all information in the tables shown above except for the TextStyle table (which is needed to define the DefaultUIFont property). You should also remove user interface properties from the Property Table. An example Property table for the Notepad sample, without a UI, is shown below. Do not reuse the GUIDs shown in the table if you copy this example.

Property Table

Property | Value
DefaultUIFont | DlgFont8
INSTALLLEVEL | 3
LIMITUI | 1
Manufacturer | Microsoft
ProductCode | {18A9233C-0B34-4127-A966-C257386270BC}
ProductLanguage | 1033
ProductName | MNP2000
ProductVersion | 01.40.0000
UpgradeCode | {908E378A-9551-4772-BF1D-5CFAF6FD9CB4}

A package without a user interface can be installed from the command line or from a program. To install a package from the command line use the methods described in Command Line Options. To install a package from a program use the methods described in Using Installer Functions. Always run validation on a new package before attempting to install a new package for the first time.

Continue


Validating an Installation Database

Authors of installation packages should always run validation on their packages before attempting to install the package for the first time and rerun validation whenever making any changes to the package. Validation scans the database for errors that may appear valid individually but that cause incorrect behavior in the context of the whole database. Attempting to install a package that fails validation can damage the user's system. See the sections Package Validation and Internal Consistency Evaluators - ICEs.

You can validate the sample package using Orca or Msival2.exe (both are provided with the Windows installer SDK). To view the help for Msival2.exe change directories and enter on the command line.

Msival2 -?

The .cub file darice.cub is also provided with the SDK. This file contains the ICE custom actions needed by Msival2.exe to perform validation. To validate the MNP2000.msi enter

msival2 MNP2000.msi Darice.cub

For a description of the error and warning messages returned by validation see the ICE Reference. Correct all the errors in the package and rerun validation as necessary until the package passes validation without errors.

Once the package passes validation, you can install the sample package by clicking on the MNP2000.msi icon or from the command line using the Command Line Options.

This completes the sample installation.

Next example

An Upgrade Example


An Upgrade Example

The following sections present an example of authoring an upgrade package for the application described in An Installation Example. An example of a minimal user interface for this sample is provided in the Platform SDK Components for Windows Installer Developers as the file Uisample.msi. If you have the SDK, you have access to all the tools and data necessary to reproduce the sample installation package, user interface, and sample upgrade package.

This example illustrates how to create a Windows Installer package that upgrades the hypothetical product MNP2000 to a new product called MNP2001. The example upgrade package applies a major upgrade to the product which requires changing the product code. For more information about major upgrades, see the topic on Major Upgrades in the Patching and Upgrades section.

The sample upgrade package has the following specifications:

  • To qualify to receive this upgrade to MNP2001, a user must have previously installed the 1.0 to 1.4 (inclusive) versions of English language MNP2000 using the Windows Installer.
  • When a user attempts to install the upgrade package, the upgrade functionality of Windows Installer searches the user's computer for any products that qualify for the upgrade.
  • The Windows Installer migrates all the of the original product's feature settings to the upgraded product.
  • The installer removes all obsolete features from the user's computer.
  • The installer installs all new features belonging to the upgrade.
  • An uninstall of the upgrade package removes the product from the user's computer, and does not restore the earlier version of the product.
  • The sample upgrade updates shortcuts to new files and features.

    Planning a Major Upgrade

    Importing Original Installation Database

    Updating Directory Structure for an Upgrade

    Updating Files and File Attributes for an Upgrade

    Updating Components for an Upgrade

    Updating Features for an Upgrade

    Updating Shortcuts for an Upgrade

    Updating Upgrade Table for an Upgrade

    Updating Properties for an Upgrade

    Updating Sequence Tables for an Upgrade

    Updating Summary Information for an Upgrade

    Validating an Installation Upgrade


Planning a Major Upgrade

If the Windows Installer is used for the installation and setup of an application, later upgrades of that application can be handled by installing an upgrade package. Setup developers may choose to author an upgrade package by modifying the original installation package. This approach is illustrated by the following upgrade example.

The installation of the original product, MNP2000, followed by the installation of the upgrade package provides the user with the following files required by the product MNP2001.

File | Description | Path to source | Path to target
Redpark.exe | Text editor executable file. Unchanged from previous products. | C:\Sample\Notepad\Redpark.exe | [ProgramFilesFolder]\Red_Park\Redpark.exe
Readme.txt | An information file. Unchanged from previous products. | C:\Sample\Notepad\Readme.txt | [ProgramFilesFolder]\Red_Park\Readme.txt
Help.txt | Help manual. Unchanged from previous products. | C:\Sample\Notepad\Help.txt | Not installed. Always run-from-source.
Baseba01.txt | Baseball game schedule for year 2001. | C:\Sample\Notepad\Events\Baseba01.txt | [ProgramFilesFolder]\Red_Park\Sports\Baseball.txt
Footba01.txt | Football game schedule for year 2001. | C:\Sample\Notepad\Events\Footba01.txt | [ProgramFilesFolder]\Red_Park\Sports\Football.txt
Basket01.txt | Basketball game schedule for year 2001. | C:\Sample\Notepad\Events\Basket01.txt | [ProgramFilesFolder]\Red_Park\Sports\Basket01.txt
Dance01.txt | Dance performances for year 2001. | C:\Sample\Notepad\Events\Dance01.txt | [ProgramFilesFolder]\Red_Park\Arts\Dance.txt
Concert01.txt | Music performances for year 2001. | C:\Sample\Notepad\Events\Concer01.txt | [ProgramFilesFolder]\Red_Park\Arts\Concert.txt
Opera01.txt | Opera performances for year 2001. | C:\Sample\Notepad\Events\Opera01.txt | [ProgramFilesFolder]\Red_Park\Arts\Opera01.txt
Januar01.txt | Admissions in January of year 2001. | C:\Sample\Notepad\Gate\Januar01.txt | [ProgramFilesFolder]\Red_Park\Gate\January.txt
NewYea01.txt | Admissions on New Years Day of year 2001. | C:\Sample\Notepad\Gate\Holidays\NewYea01.txt | [ProgramFilesFolder]\Red_Park\Gate\NewYears.txt
Memori01.txt | Admissions on Memorial Day of year 2001. | C:\Sample\Notepad\Gate\Holidays\Memori01.txt | [ProgramFilesFolder]\Red_Park\Gate\Memori01.txt

Installation of the upgrade package removes all the features installed with the original product that are not being used by the upgraded product. For example, when upgrading from MNP2000, installation of the upgrade removes the following files from the user's computer:

Baseball.txt

Football.txt

Dance.txt

Concert.txt

January.txt

NewYears.txt

Installation of the upgrade package writes the following values in the user's registry under

HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Notepad Sample.

Name | Value
lfCharSet | 0
lfClipPrecision | 2
lfFaceName | FixedSys
lfItalic | 0
lfOrientation | 0
lfOutPrecision | 1
fSavePageSetting | 0
lfPitchAndFamily | 49
iPointSize | 120
lfQuality | 2
lfStrikeOut | 0
lfWeight | 400
fWrap | 0

The upgrade udates old shortcuts to the following shortcuts. One of these shortcuts may be selected during setup as an advertised shortcut so that the user can install-on-demand the Baseball feature.

Name | Shortcut location | Shortcut target
sNotepad | [ProgramFilesFolder]\Red_Park\Menu\ | [ProgramFilesFolder]\Red_Park\Redpark.exe
sReadme | [ProgramFilesFolder]\Red_Park\Menu\ | [ProgramFilesFolder]\Red_Park\Readme.txt
sHelp | [ProgramFilesFolder]\Red_Park\Menu\ | [ProgramFilesFolder]\Sample\Notepad\Help.txt
sBaseball | [ProgramFilesFolder]\Red_Park\Menu\ | [ProgramFilesFolder]\Red_Park\Sports\Baseba01.txt
sFootball | [ProgramFilesFolder]\Red_Park\Menu\ | [ProgramFilesFolder]\Red_Park\Sports\Footba01.txt
sBasketball | [ProgramFilesFolder]\Red_Park\Menu\ | [ProgramFilesFolder]\Red_Park\Sports\Basketba01.txt
sDance | [ProgramFilesFolder]\Red_Park\Menu\ | [ProgramFilesFolder]\Red_Park\Arts\Dance01.txt
sConcert | [ProgramFilesFolder]\Red_Park\Menu\ | [ProgramFilesFolder]\Red_Park\Arts\Concer01.txt
sOpera | [ProgramFilesFolder]\Red_Park\Menu\ | [ProgramFilesFolder]\Red_Park\Arts\Opera01.txt
sJanuary | [ProgramFilesFolder]\Red_Park\Menu\ | [ProgramFilesFolder]\Red_Park\Gate\Januar01.txt
sNewYears | [ProgramFilesFolder]\Red_Park\Menu\ | [ProgramFilesFolder]\Red_Park\Gate\NewYea01.txt
sMemorial | [ProgramFilesFolder]\Red_Park\Menu\ | [ProgramFilesFolder]\Red_Park\Gate\Memori01.txt

When a user uninstalls the upgrade package, Windows Installer completely removes all versions of the product from the user's computer. The user is not left with any parts of MNP2000 or MNP2001.

Continue


Importing Original Installation Database

Begin authoring the upgrade package by copying the installation package and source directory tree of the of original product. Instructions for authoring the installation package for MNP2000 are given in An Installation Example. You should copy the contents of the following folders:

C:\Sample\MNP2000.msi

C:\Sample\Notepad\

C:\Sample\Binary\

C:\Sample\Icon\

Update the contents of the Notepad folder so that they match the source described in Planning a Major Upgrade. Remove all obsolete source files, such as Baseball.txt, and replace with the updated files, such as Baseba01.txt. Add the additional new files provided by the upgrade, such as Opera01.txt.

Rename MNP2000.msi to MNP2001.msi. In subsequent steps you will use a table editor to modify this database into the .msi file for the upgrade. Database tables that are not explicitly modified in the subsequent sections are identical to the tables in the original product's database, MNP2000.msi.

Continue


Updating Directory Structure for an Upgrade

Use the database editor Orca that is provided with the SDK, or another editor, to open the Directory Table in MNP2001.msi. The directory structure of the sample upgrade is the same as the directory structure of the original product and no changes are required to the original Directory table described in Specifying Directory Structure.

Continue


Updating Files and File Attributes for an Upgrade

Because the upgrade updates the files used by the application, you must modify the File table of the database. Use the database editor Orca that is provided with the SDK, or another editor to open MNP2001.msi and enter the following data into the File Table.

File Table

File | Component_ | FileName | FileSize | Version | Language | Attributes | Sequence
Baseba01.txt | Baseball | Baseba01.txt | 1000 |  |  | 0 | 1
Concer01.txt | Concert | Concer01.txt | 1000 |  |  | 0 | 1
Dance01.txt | Dance | Dance01.txt | 1000 |  |  | 0 | 1
Opera01.txt | Opera | Opera01.txt | 1000 |  |  | 0 | 1
Footba01.txt | Football | Footba01.txt | 1000 |  |  | 0 | 1
Basket01.txt | Basketball | Basket01.txt | 1000 |  |  | 0 | 1
Help.txt | Help | Help.txt | 1000 |  |  | 0 | 1
Januar01.txt | January | Januar01.txt | 1000 |  |  | 0 | 1
NewYea01.txt | NewYears | NewYea01.txt | 1000 |  |  | 0 | 1
Memori01.txt | Memorial | Memori01.txt | 1000 |  |  | 0 | 1
Redpark.exe | Notepad | Redpark.exe | 45328 |  |  | 0 | 1
Readme.txt | Notepad | Readme.txt | 1000 |  |  | 0 | 1

Continue


Updating Components for an Upgrade

By design, users of the fictitious MNP2000 product should never use upgraded files such as Baseba01.txt. Therefore the updated files are by definition incompatible with the original product and Windows Installer components, such as Baseball, containing these files must be assigned new component codes. New files, such as Opera01.txt, are introduced as a part of a new component with a unique component code. Because the original product and upgrade use the same Notepad component, the component code of this component is unchanged. For more information about when component code must be changed, see Changing the Component Code.

Use Orca or another database editor to enter the following data into the Component table of MNP2001.msi. Do not reuse the GUIDs shown below in the ComponentId column in your sample.

Component Table

Component | ComponentId | Directory_ | Attributes | Condition | Keypath
Baseball | {2951190A-6AF8-4D7F-AA16-D256405C277A} | SPORTDIR | 2 |  | Baseba01.txt
Basketball | {E1AAB6B0-FEC6-4F18-B765-3B05A81CEACB} | SPORTDIR | 2 |  | Basket01.txt
Concert | {C28C5064-AA84-4431-AC69-FC1321DF18AF} | ARTSDIR | 2 |  | Concer01.txt
Dance | {1AC2B14D-D5F4-4642-9F7A-EE81BF59B3E2} | ARTSDIR | 2 |  | Dance01.txt
Opera | {C2DABF7E-1EF6-458D-84B1-AAC1127CED26} | ARTSDIR | 2 |  | Opera01.txt
Football | {92AA30F4-7AC5-4DFA-801E-988CF3DAA4DC} | SPORTDIR | 2 |  | Footba01.txt
Help | {AD10EB50-33C1-11D3-91D6-00C04FD70856} | NOTEPADDIR | 2 |  | Help.txt
January | {E90CD0E6-ED8D-4F88-B000-27BD2B482C6C} | MONDIR | 2 |  | Janua01.txt
NewYears | {1EEF8C53-F7C0-405C-8FE3-2B0FE54B0114} | HOLDIR | 2 |  | NewYea01.txt
Memorial | {BA81ACF7-4D43-424F-93B0-8845A2DF1C02} | HOLDIR | 2 |  | Memori01.txt
Notepad | {19BED232-30AB-11D3-91D3-00C04FD70856} | NOTEPADDIR | 2 |  | Redpark.exe

Continue


Updating Features for an Upgrade

The sample upgrade package adds three new features to the original product:

  • Basketball, a new child feature of the Sport feature.
  • Opera, a new child feature of the Arts feature.
  • Memorial, a new child feature of the Gate feature.

Use your database editor to open MNP2001.msi and enter the following data into the Feature Table.

Feature Table

Feature | Feature_Parent | Title | Description | Display | Level | Directory_ | Attributes
Arts |  | Arts | Arts events at Red Park. | 18 | 3 | NOTEPADDIR | 0
Baseball | Sport | Baseball | Baseball Games | 17 | 3 | SPORTDIR | 32
Concert | Arts | Concert | Concert events at Red Park | 19 | 3 | ARTSDIR | 2
Dance | Arts | Dance | Dance events at Red Park | 21 | 3 | ARTSDIR | 2
Football | Sport | Football | Football Games | 13 | 3 | SPORTDIR | 2
Gate |  | Gate | Red Park's Admissions | 6 | 3 | NOTEPADDIR | 0
Help | Notepad | Help | Help file. | 5 | 3 | NOTEPADDIR | 1
January | Gate | January | January Admissions | 7 | 3 | MONDIR | 2
NewYears | January | New Years Day | New Years Day Admissions | 9 | 3 | HOLDIR | 2
Notepad |  | Notepad | Notepad Editor | 1 | 3 | NOTEPADDIR | 0
Readme | Notepad | Readme | Readme File | 3 | 3 | NOTEPADDIR | 0
Sport |  | Sport Events | Sport Events at Red Park | 12 | 3 | NOTEPADDIR | 0
Basketball | Sport | Basketball | Basketball Games | 15 | 3 | SPORTDIR | 2
Opera | Arts | Opera | Opera Performances | 23 | 3 | ARTSDIR | 2
Memorial | Gate | Memorial Day | Memorial Day Admissions | 11 | 3 | HOLDIR | 2

Use your database editor to open MNP2001.msi and enter the following data into the empty FeatureComponents Table.

Feature_ | Component_
Baseball | Baseball
Concert | Concert
Dance | Dance
Football | Football
Help | Help
January | January
NewYears | NewYears
Notepad | Notepad
Readme | Notepad
Basketball | Basketball
Opera | Opera
Memorial | Memorial

Continue


Updating Shortcuts for an Upgrade

The sample upgrade package updates shortcuts to the new files and features.

Use your database editor to open MNP2001.msi and enter the following data into the Shortcut Table.

Shortcut | Directory_ | Name | Component_ | Target | Arguments | Description | Hotkey | Icon_ | IconIndex | ShowCmd | WkDir
sBaseball | MENUDIR | Baseba01.txt | Baseball | Baseball |  |  |  | orca_icon.exe |  |  |
sConcert | MENUDIR | Concer01.txt | Concert | [#Concer01.txt] |  |  |  |  |  |  |
sDancell | MENUDIR | Dance01.txt | Dance | [#Dance01.txt] |  |  |  |  |  |  |
sFootball | MENUDIR | Footba01.txt | Football | [#Footba01.txt] |  |  |  |  |  |  |
sHelp | MENUDIR | Help.txt | Help | [#Help.txt] |  |  |  |  |  |  |
sJanuary | MENUDIR | Januar01.txt | January | [#Januar01.txt] |  |  |  |  |  |  |
sNewYears | MENUDIR | NewYea01.txt | NewYears | [#NewYea01.txt] |  |  |  |  |  |  |
sNotepad | MENUDIR | Redpark.exe | Notepad | [#Redpark.exe] |  |  |  |  |  |  |
sReadme | MENUDIR | Readme.txt | Notepad | [#Readme.txt] |  |  |  |  |  |  |
sMemorial | MENUDIR | Memori01.txt | Memorial | [#Memori01.txt] |  |  |  |  |  |  |
sBasketball | MENUDIR | Basketba01.txt | Basketball | [#Basketba01.txt] |  |  |  |  |  |  |
sOpera | MENUDIR | Opera01.txt | Opera | [#Opera.txt] |  |  |  |  |  |  |

Continue


Updating Upgrade Table for an Upgrade

To apply a major upgrade using the Windows Installer, the original product installation package must specify an UpgradeCode Property, described in Preparing an Application for Future Major Upgrades, and the upgrade package must have an Upgrade table.

For more information about major upgrades, see Major Upgrades in Patching and Upgrades.

The installation package of MNP2000.msi was assigned an UpgradeCode property, as described in the section Specifying Properties.

Windows Installer applys the upgrade if the user has already installed the 1.0 to 1.4 versions (inclusive) of English language MNP2000. Windows Installer migrates all of the original product's feature settings to the upgraded product. The installer removes the files belonging to the original products not being used by the product's upgrade.

If your copy of MNP2001.msi does not include an Upgrade Table, use Orca, or another table editor, to import an empty Upgrade Table into the database from Schema.msi. The SDK provides a copy of Schema.msi. Use your database editor to open MNP2001.msi and enter the following data into the empty Upgrade Table.

UpgradeCode | VersionMin | VersionMax | Language | Attributes | Remove | ActionProperty
{908E378A-9551-4772-BF1D-5CFAF6FD9CB4} | 01.00.0000 | 01.40.0000 | 1033 | 769 |  | OLDAPPFOUND

Continue


Updating Properties for an Upgrade

Because the upgrade changes the name of the .msi file and changes the component code of some components, the product code of the upgrade must be changed from that of the original product. For a description of the cases where an upgrade is required to change the ProductCode property, see Changing the Product Code. An upgrade that changes the ProductCode is referred to as a Major Upgrade.

The upgrade package's ProductName property, ProductVersion property, ProductLanguage property, and UpgradeCode property may be changed, or left unchanged, from the original product. Based upon the values of these properties, the Windows Installer may determine whether to apply future upgrade packages to the current upgrade.

The property specified in the ActionProperty column of the Upgrade table must be added to the SecureCustomProperties Property.

Use your database editor to open MNP2001.msi and enter the following data into the Property Table. The list provides links to the reference topics for built-in installer properties. The property names that are not links are author-defined properties. Many of the properties were imported from Uisample.msi that comes with the SDK. For details, see Importing the User Interface.

Property Table

Property | Value
ARPHELPLINK | http://www.microsoft.com/management
BannerBitmap | bannrbmp
ButtonText_Back | < &Back
ButtonText_Browse | Br&owse
ButtonText_Cancel | Cancel
ButtonText_Exit | &Exit
ButtonText_Finish | &Finish
ButtonText_Ignore | &Ignore
ButtonText_Install | &Install
ButtonText_Next | &Next >
ButtonText_No | &No
ButtonText_OK | OK
ButtonText_Remove | &Remove
ButtonText_Reset | &Reset
ButtonText_Resume | &Resume
ButtonText_Retry | &Retry
ButtonText_Return | &Return
ButtonText_Yes | &Yes
CompleteSetupIcon | completi
ComponentDownload | ftp://anonymous@microsoft.com/components/
CustomSetupIcon | custicon
DefaultUIFont | DlgFont8
DialogBitmap | dlgbmp
DlgTitleFont | {&DlgFontBold8}
ErrorDialog | ErrorDlg
ExclamationIcon | exclamic
False | 0
Iagree | No
InfoIcon | info
InstallerIcon | insticon
INSTALLLEVEL | 3
InstallMode | Typical
Manufacturer | Microsoft
PIDTemplate | 12345<###-%%%%%%%>@@@@@
ProductCode | {34CF587C-1D8F-4DD5-ADFE-440F4B593987}
ProductID | none
ProductLanguage | 1033
ProductName | MNP2001
ProductVersion | 01.50.0000
Progress1 | Installing
Progress2 | installs
PROMPTROLLBACKCOST | P
RemoveIcon | removico
RepairIcon | repairic
Setup | Setup
True | 1
UpgradeCode | {908E378A-9551-4772-BF1D-5CFAF6FD9CB4}
Wizard | Setup Wizard
SecureCustomProperties | OLDAPPFOUND

Continue


Updating Sequence Tables for an Upgrade

The sequence tables of the sample upgrade package are the same as in the original product. See the following sections:

Importing the InstallExecuteSequence

Importing the InstallUISequence

Importing the AdminExecuteSequence

Importing the AdminUISequence

Importing the AdvtExecuteSequence

Updating Summary Information for an Upgrade

Continue


Updating Summary Information for an Upgrade

The package code of the upgrade package must be changed from that of the original product. The package code is stored in the Revision Number Summary Property. For details, see Package Codes. Use Msiinfo.exe, or another editor, to change the summary information of MNP2001.msi as described in Adding Summary Information.

Summary information property | Data | Notes
Template (Platform and Language) | ;1033 | Platform and language used by the database. Leaving the platform field empty indicates the package is platform independent. The ProductLanguage property from the database is typically used for this summary property. The sample's Language ID indicates that the package uses U.S. English.
Revision Number (Package Code) | {A0EC5348-1D02-4FF6-93F5-61BD7AC1772E} | This is the package code GUID that uniquely identifies the sample package. If you reproduce this sample, use a utility such as GUIDGEN to generate a different GUID for your package. The results of GUIDGEN contain lowercase characters, note that you must change all lowercase characters to uppercase for a valid package code.
Page Count (Minimum Installer Version) | 110 | For Windows Installer version 1.0, this property should be set to the integer 100. For Windows Installer version 1.1, this property should be set to the integer 110.
Word Count (Type of Source) | 0 | The global source type for the package is long file names and uncompressed. For more information, see Compressed and Uncompressed Sources and the description of the Attributes column of the File table.
Title | Installation Database | Informs users that this database is for an installation rather than a transform or a patch.
Subject | MNP2001 | File browsers can display this as the product to be installed with this database.
Keywords | Installer, MSI, Database | File browsers that are capable of keyword searching can search for these words.
Author | Microsoft Corporation | Name of the product's manufacturer.
Comments | This installer database contains the logic and data required to install Notepad. | Informs users about the purpose of this database.
Creating Application | Orca | Application used to create the installation database. The sample specifies the Orca database editor as an example.
Security | 0 | The sample database is unrestricted read-write.

See Also

Package Codes

Continue


Validating an Installation Upgrade

Whenever making any changes to the package, authors of upgrade packages should always run validation on their packages before attempting to install the package for the first time and rerun validation. Run validation on an upgrade package in the same way as for an installation package. For details, see Validating an Installation Database.

This completes the sample upgrade package. To install the upgrade first install MNP2000.msi and then install MNP2001.msi. When you uninstall MNP2001 both the original and upgrade products are removed from your computer.

Next example

A Customization Transform Example


A Customization Transform Example

This example illustrates how a customization transform may be used to disable features and add new resources.

An administrator can permanently disable a feature by using a customization transform to enter a 0 into the Level column of the Feature table. The application of the customization transform then prevents the installation and display of that feature even if the user selects a complete installation using the UI or by setting the ADDLOCAL property to ALL on the command line. For a discussion of installation level, see Feature table and INSTALLLEVEL property.

The resources needed to customize an application can be deployed by using a customization transform to add one or more new components. The transform must add one or more new features to contain these new components. For the rules that should be followed when deploying resources, such as files, registry keys, or shortcuts, see Using Transforms to Add Resources.

This example illustrates how to create a transform to customize the installation of the application described in An Installation Example. The original installation package installs all the features of the sample application, including the feature Gate, which enables users to view admissions information for the Red Park Arena. Some groups of users only need the application features that give event scheduling information, and do not need the Gate feature. These groups also need to get a special phone list. The transform must therefore do two things: 1) customize the installation so that this group only receives the application features they need and 2) provide the resources needed for the new phone list.

An example of a minimal user interface for this sample is provided in the Platform SDK Components for Windows Installer Developers as the file Uisample.msi. If you have the SDK, you have access to all the tools and data necessary to reproduce the sample installation package, user interface, and customization transform.

The customization transform has the following specifications:

  • The customization transform is embedded inside the MNP2000.msi file to guarantee that it is always available with the installation database.
  • Installing MNP2000.msi with the customization transform does not install the Gate feature, child features of the Gate feature, or any of the components of the Gate feature, even if the user selects the Complete type of installation.
  • Other applications may share some or all of the components of the Gate feature. The installation packages of these applications may install all their components on the user's computer.
  • Removing MNP2000.msi with the customization transform does not remove any of the Gate components that have been installed by other applications.
  • Installing MNP2000.msi with the customization transform also installs a new top level feature, Phone_List, and a new component, phone, which requires the installation of the resource, Phone.txt. The user accesses the Phone_List feature using a shortcut in the Menu directory.

Continue


Customizing an Original Database

Make a copy of the sample Windows Installer installation package MNP2000.msi and rename this copy MNP2000t.msi. In the following steps you will customize this file using a database table editor such as Orca, which is provided with the SDK, or another database editor.

Include the new resource file for the phone list, Phone.txt, in the Notepad folder with the other source files.

File | Description | Path to source | Path to target
phone.txt | A resource for the Phone_List feature. | C:\Sample\Notepad\phone.txt | [ProgramFilesFolder]\Red_Park\phone.txt

Use your database editor to add a record to the File Table of MNP2000t.msi for the new file.

File Table

File | Component_ | FileName | FileSize | Version | Language | Attributes | Sequence
Phone.txt | Phone | Phone.txt | 1000 |  |  | 0 | 1

As explained in the section: Using Transforms to Add Resources, the transform should add one or more new components to the installation database to contain the new phone list feature. Use your database editor to add the following record the Component Table of MNP2000t.msi.

The Phone component should be identified with a unique component ID GUID. If you are reproducing the sample, do not reuse the same component ID GUID as in the following table. Instead use a utility such as Guidgen.exe to generate a new GUID. Be sure that you use a GUID string consistent with the Windows Installer GUID data type.

Component Table

Component | ComponentId | Directory_ | Attributes | Condition | Keypath
Phone | {D152A1EC-9F7A-4E45-B0DC-ED6EE5D829F8} | NOTEPADDIR | 2 |  | Phone.txt

Use your database editor to modify the data in the Feature Table of MNP2000t.msi. Enter 0 into the Level column of the Gate feature record. This disables the Gate feature and its child features and hides these features from the UI. Note that because the INSTALLLEVEL Property is set to 3 in the Property Table, the installer does not install features with a Level of 0. Add a record for the new Phone_List feature.

Feature Table

Feature | Feature_Parent | Title | Description | Display | Level | Directory_ | Attributes
Arts |  | Arts | Arts events at Red Park. | 20 | 3 | NOTEPADDIR | 0
Baseball | Sport | Baseball | Baseball Games | 17 | 3 | SPORTDIR | 32
Concert | Arts | Concert | Concert events at Red Park | 21 | 3 | ARTSDIR | 2
Dance | Arts | Dance | Dance events at Red Park | 23 | 3 | ARTSDIR | 2
Football | Sport | Football | Football Games | 19 | 3 | SPORTDIR | 2
Gate |  | Gate | Red Park's Admissions | 6 | 0 | NOTEPADDIR | 0
Help | Notepad | Help | Help file. | 5 | 3 | NOTEPADDIR | 1
January | Gate | January | January Admissions | 10 | 3 | MONDIR | 2
NewYears | January | New Years Day | New Years Day Admissions | 11 | 3 | HOLDIR | 2
Notepad |  | Notepad | Notepad Editor | 1 | 3 | NOTEPADDIR | 0
Readme | Notepad | Readme | Readme File | 3 | 3 | NOTEPADDIR | 0
Sport |  | Sport Events | Sport Events at Red Park | 14 | 3 | NOTEPADDIR | 0
Phone_List |  | Phone List | Phone List | 24 | 3 | NOTEPADDIR | 0

Add the following record to the FeatureComponents Table of MNP2000t.msi.

FeatureComponents Table

Feature_ | Component_
Phone_List | Phone

Add a new record in the Shortcut Table to create a shortcut to the Phone_List feature.

Shortcut Table

Shortcut | Directory_ | Name | Component_ | Target | Arguments | Description | Hotkey | Icon_ | IconIndex | ShowCmd | WkDir
sPhone | MENUDIR | Phone.txt | Phone | [#Phone.txt] |  |  |  |  |  |  |

Continue


Generating a Customization Transform

You may generate a transform file by using MsiDatabaseGenerateTransform or the GenerateTransform method of the Database object. An example of this is provided in the Windows Installer SDK as the utility WiGenXfm.vbs. The following snippet, Gen.vbs, also illustrates the GenerateTransform method and is for use with Windows Scripting Host.

'Gen.vbs. Argument(0) is the original database. Argument(1) is the
'    customized database. Argument(2) is the transform file.

Option Explicit
' Connect to Windows Installer object
On Error Resume Next
Dim installer : Set installer = Nothing
Set installer = Wscript.CreateObject("WindowsInstaller.Installer")
' Open databases
Dim database1 : Set database1 =
    installer.OpenDatabase(Wscript.Arguments(0), 0)
Dim database2 : Set database2 =
    installer.OpenDatabase(Wscript.Arguments(1), 0)
' Generate transform
Dim transform : transform = Database2.GenerateTransform(Database1,
    Wscript.Arguments(2))

To generate the transform file MNPtrans.mst from the original MNP2000.msi database and the MNP2000t.msi database you modified in Customizing an Original Database, change directories to the folder containing Gen.vbs, the original database, and the updated installer database and enter the following command line.

Cscript.exe Gen.vbs MNP2000.msi MNP2000t.msi MNPtrans.mst

Continue


Adding Summary Information to Customization Transform

To apply the customization transform during an installation of the product, you must add a Summary Information Stream to the transform file MNPtrans.mst generated in Generating a Customization Transform.

You may generate summary information for a transform using MsiCreateTransformSummaryInfo or the CreateTransformSummaryInfo Method. The following snippet, Sum.vbs, illustrates the CreateTransformSummaryInfo Method and is for use with Windows Scripting Host. Note that this example performs no validation and suppresses no error conditions.

'Sum.vbs. Argument(0) is the original database. Argument(1) is the
'    customized database. Argument(2) is the transform file.

Option Explicit

' Connect to Windows Installer object
On Error Resume Next
Dim installer : Set installer = Nothing
Set installer = Wscript.CreateObject("WindowsInstaller.Installer")

' Open databases and transform
Dim database1 : Set database1 =
    installer.OpenDatabase(Wscript.Arguments(0), 0)
Dim database2 : Set database2 =
    installer.OpenDatabase(Wscript.Arguments(1), 0)
Dim transform : transform = Wscript.Arguments(2)

' Create and add Summary Information
Dim transinfo : transinfo =
    Database2.CreateTransformSummaryInfo(Database1, transform,0,0)

To create and add summary information to the transform file MNPtrans.mst you created in Generating a Customization Transform, change directories to the folder containing Gen.vbs, the original database, the updated database, and the transform, and enter the following command line.

Cscript.exe Sum.vbs MNP2000.msi MNP2000t.msi MNPtrans.mst

Click on the MNP2000.msi icon to launch an install or use the following command line.

msiexec /i MNP2000.msi

This installs the product without the customizations. To install with the customization, enter the following command line. Note that the value of the TRANSFORMS Property refers to transform file located at the source.

msiexec /i MNP2000.msi TRANSFORMS=MNPtrans.mst

The Gate feature does not appear in the feature selection tree and the components of the Gate feature are not installed even if a Complete type of installation is selected in the user interface.

Continue


Embedding Customization Transforms as Substorage

You may store the customization transform in a storage of the Windows installer package to guarantee that the transform is always available when the installation package is available. See Embedded Transforms. An example of this is provided in the Windows Installer SDK as the utility WiSubStg.vbs. The following snippet, Emb.vbs, also illustrates the use of the _Storages Table to add an embedded transform and is for use with Windows Scripting Host.

'Emb.vbs. Argument(0) is the original database. Argument(1) is the
'    path to the transform file. Argument(2) is the name of the storage.
'
Option Explicit

' Connect to Windows Installer object
On Error Resume Next
Dim installer : Set installer = Nothing
Set installer = Wscript.CreateObject("WindowsInstaller.Installer")

' Evaluate command-line arguments and set open and update modes
Dim databasePath: databasePath = Wscript.Arguments(0)
Dim importPath  : importPath = Wscript.Arguments(1)
Dim storageName : storageName = Wscript.Arguments(2)

' Open database and create a view on the _Storages table
Dim sqlQuery : sqlQuery = "SELECT `Name`,`Data` FROM _Storages"
Dim database : Set database = installer.OpenDatabase(databasePath, 1)
Dim view     : Set view = database.OpenView(sqlQuery)

'Create and Insert the row.
Dim record   : Set record = installer.CreateRecord(2)
record.StringData(1) = storageName
view.Execute record

'Insert storage - copy data into stream
record.SetStream 2, importPath
view.Modify 3, record
database.Commit
Set view = Nothing
Set database = Nothing

To add a storage named MNPtrans1 to MNP2000.msi, and containing the transform you created in Adding Summary Information to Customization Transform, change directories to the folder containing Emb.vbs, the original database, and the transform file, then enter the following command line.

Cscript.exe Emb.vbs MNP2000.msi MNPtrans.mst MNPtrans1

This completes the customization transform example. After embedding the transform in MNPtrans.mst, the transform is always available with the installation package. The file MNPtrans.mst does not need to be located at the source to apply the transform.

Remove MNPtrans.mst from the folder containing the sample installation package. Click on the MNP2000.msi icon to launch an install or use the following command line.

msiexec /i MNP2000.msi

Note that this installs the product without the customizations. To install with the customizations, enter the following command line. Use a colon to indicate that the value of the TRANSFORMS Property refers to an embedded transform.

msiexec /i MNP2000.msi TRANSFORMS=:MNPtrans1

Note that the Gate feature does not appear in the feature selection tree and that the components of the Gate feature are not installed even if a Complete type of installation is selected in the user interface.

Next example

A Small Update Patching Example


A Small Update Patching Example

This example illustrates how to create a patch package that applies a small update to the sample installation package discussed in An Installation Example. A small update makes changes to one or more application files that are judged to be too minor to warrant changing the product code. For more information see Patching and Upgrades.

This example illustrates how to create a Windows Installer patch package that updates the Concert feature of the hypothetical product MNP2000 to fix an error in the original product. The example patch package applies a small update to the product that does not require changing the product code. See the topic on Major Upgrades in the Patching and Upgrades section for more information about major upgrades.

The sample upgrade package has the following specifications:

  • It corrects a minor error in the Concert schedule displayed by the Concert feature.
  • It updates the package code to reflect the installation package has changed.
  • The small update can be applied by patching the local installation of the product.

Continue


Planning a Small Update Patch

The Concert feature file of the original product, MNP2000, contains an error in the Concert.txt file. Because the Windows Installer was used for the installation and setup of the application, minor fixes to the application may be handled by installing a small update patch package. A small update makes changes to one or more application files that are judged to be too minor to warrant changing the product code. The following example describes how to create a Windows Installer patch package that can apply the small update and provide a quick fix to the MNP2000 product.

To create the small update first obtain a fully uncompressed image of the MNP2000 product that includes the error in Concert.txt. The image must include MNP2000.msi and all the source files described in Planning the Installation. In the following discussion this is called the Target image. The Target image must be fully uncompressed because the patch creation process is unable to generate binary patches for files compressed in cabinets. Put the .msi file and all the source files of the Target image into a folder named Target.

Next, obtain a fully uncompressed image of the MNP2000 product with a Concert.txt file that has been fixed. This is called the Upgraded image in the following discussion. Use an installation database editing tool, such as Orca, to update the .msi file. For example, if the size of the corrected Concert.txt is smaller than the original, be sure to enter the new size in the FileSize field of the File table of the upgraded image. Note that because the package has changed you must assign a new package code in the Revision Number Summary Property. Put the .msi file and all the source files of the Upgraded image into a folder named Upgraded.

Note that Windows Installer version 1.2 cannot create a patch between two identical .msi files because creating the transform fails, which causes the patch creation process to fail. The information in the two databases must be different, not merely the summary information stream. For the purposes of this example, assume that the size of the Concert.txt file changes. This means that FileSize fields in the File tables of the Target and Upgraded database contain different data.

File Table (record from Target Image)

File | Component_ | FileName | FileSize | Version | Language | Attributes | Sequence
Concert.txt | Concert | Concert.txt | 1000 |  |  | 0 | 1

File Table (record from Upgraded Image)

File | Component_ | FileName | FileSize | Version | Language | Attributes | Sequence
Concert.txt | Concert | Concert.txt | 900 |  |  | 0 | 1

Continue


Creating a Patch Creation Properties File

To reproduce the sample patch package, you need a software tool capable of creating and editing a Windows Installer patch package. Several patch package creation tools are available from independent software vendors. The example discussed in the following sections uses a Windows Installer database editor called Orca to author a patch creation properties file (.pcp extension). The .pcp file may be used with the utilities Msimsp.exe and Patchwiz.dll to generate a Windows Installer patch package (.msp extension). Orca, Msimsp.exe, and Patchwiz.dll are provided in the Platform SDK Components for Windows Installer Developers.

A blank patch creation properties file, template.pcp, is also provided with the SDK. Make a copy of template.pcp and rename this copy MNP2000.pcp. Use Orca or another database editor to enter the following data into the Properties table of MNP2000.pcp. The Properties table contains global settings for the patch package.

Properties Table

Name | Value
AllowProductCodeMismatches | 1
AllowProductVersionMajorMismatches | 1
ApiPatchingSymbolFlags | 0x00000000
DontRemoveTempFolderWhenFinished | 1
IncludeWholeFilesOnly | 0
ListOfPatchGUIDsToReplace |
ListOfTargetProductCodes | *
PatchGUID | {5406B219-A1AC-4BC4-8695-72292C8195AC}
PatchOutputPath | c:\output.msp
PatchSourceList | PatchSourceList

Use the database editor to enter the following data into the ImageFamilies table of MNP2000.pcp. The ImageFamilies table contains information to be added to the Media table during patching.

ImageFamilies Table

Family | MediaSrcPropName | MediaDiskId | FileSequenceStart | DiskPrompt | VolumeLabel
MNPapps | MNPSrcPropName | 2 | 1000 |  |

Enter the following data into the UpgradedImages table of MNP2000.pcp. The UpgradedImages table contains information about the Upgraded image you created in Planning a Small Update Patch.

UpgradedImages Table

Upgraded | MsiPath | PatchMsiPath | SymbolPaths | Family
MNP_fixed | C:\Note_Installer\Patch\Upgraded\MNP2000.msi |  |  | MNPapps

Enter the following data into the TargetImages table of MNP2000.pcp. The TargetImages table contains information about the Target image.

TargetImages Table

Target | MsiPath | SymbolPaths | Upgraded | Order | ProductValidateFlags | IgnoreMissingSrcFiles
MNP_error | C:\Note_Installer\Patch\Target\MNP2000.msi |  | MNP_fixed | 1 |  | 0

For the sample patch package, leave the following tables in MNP2000.pcp blank.

UpgradedFiles_OptionalData Table

FamilyFileRanges Table

TargetFiles_OptionalData Table

ExternalFiles Table

UpgradedFilesToIgnore Table

Continue


Generating a Patch Package

The recommended method for generating a patch package is to use a patch creation tool such as Msimsp.exe to call UiCreatePatchPackage in Patchwiz.dll. Msimsp.exe and PatchWix.dll are provided in the Windows Installer SDK. The source code for Patchwiz.dll is also provided as an example so that you can customize and enhance the patch creation process.

The following example command line uses Msimsp.exe and the .pcp file created in Creating a Patch Creation Properties File to generate the sample patch package MNP2000.msp.

Msimsp.exe -s C:\Note_Installer\Patch\MNP2000.pcp -p C:\Note_Installer\Patch\MNP2000.msp

An authored patch creation tool may generate the patch package by calling UiCreatePatchPackage as follows.

UiCreatePatchPackage (C:\Note_Installer\Patch\MNP2000.pcp, C:\Note_Installer\Patch\MNP2000.msp, NULL, NULL, %TEMP%\~pcw_tmp.tmp\, TRUE)

Note that Windows Installer version 1.2 cannot create a patch between two identical .msi files because creating the transform fails, which causes the patch creation process to fail. The information in the two databases must be different, not merely the summary information stream. See Planning a Small Update Patch.

Continue


Applying a Patch Package to a Local Installation

You may apply the small update to a local installation of MNP2000 with the sample patch MNPpatch.msp created in Generating a Patch Package. The general procedure is discussed in the section Small Updates by Patching the Local Installation of the Product.

Install the original MNP2000 product locally on your computer. Verify that this has the error Concert.txt that the small update is to fix. Next launch the installation by entering the following command line.

msiexec /p MNP2000.msp REINSTALL=ALL REINSTALLMODE=omus

Rexamine the Concert.txt belonging to MNP2000 to verify that the installer has applied the small update to fix this file.

To apply the small update to an administrative image, see Applying a Patch Package to an Administrative Installation.

Continue


Applying a Patch Package to an Administrative Installation

You may apply the small update to an administrative source image of MNP2000.msi by installing the sample patch MNP2000.msp created in Generating a Patch Package. The update can then be propagated to users by requesting that they reinstall the application from the new administrative source image.

An administrator can use the following command line to update the administrative source image located at //server/MNP2000.msi to a new source image that is the same as would be produced by an administrative installation from a fully updated CD-ROM.

msiexec /a //server/MNP2000.msi /p MNP2000.msp

Members of the workgroup using MNP2000 then must reinstall the application from the new administrative source image to receive the update.

To completely reinstall the applications and cache the updated .msi file on the user's computer, users may enter either of the following commands.

msiexec /fvomus //server/MNP2000.msi

msiexec /I //server/MNP2000.msi REINSTALL=ALL REINSTALLMODE=vomus

To reinstall only the updated Concert feature and cache the updated .msi file on the user's computer, users may enter the following command.

msiexec /I //server/MNP2000.msi REINSTALL=Concert REINSTALLMODE=vomus

Next example

A Localization Example


A Localization Example

This example illustrates how to localize the Windows Installer package described in An Installation Example. The original installation package is changed from an English into French language version.

The localization sample has the following specifications:

  • The installation UI for the application MNP2000 should be changed from English to French.
  • The French version of MNP2000 includes Readme.txt and Help.txt files written in the French language.
  • The French version includes a list of travel agents in France that can provide tickets to Red Park Arena. This list (provided as a new file, Fre.txt) is not a part of the English version.

The general procedure for localizing an installation is described in the section Localizing a Windows Installer Package.

Copy the English version of MNP2000.msi and all the source files described in Planning the Installation into a new folder. Change the name of the MNP2000.msi in the folder to MNPFren.msi. In the following sections you will modify this copy to localize the application into French.

Continue


Checking the Installation Database Code Page

A code page is an internal table that the operating system uses to map symbols (letters, numerals, and punctuation characters) to a character number. Different code pages provide support for the character sets used in different countries. Code pages are referred to by number; for example, code page 932 represents the Japanese character set, and code page 950 represents one of the Chinese character sets. See Localizing the Error and ActionText Tables for a list of ASCII code pages.

The same ASCII code page, 1252, may be used for English and French. Therefore the code page for the database MNP2000.msi (English) does not need to be reset to change the installation to French.

For more information about setting the code page see Code Page Handling (Windows Installer).

Continue


Importing Localized Error and ActionText Tables

Localized language versions of the Error Table and ActionText Table are provided by the Windows Installer SDK. The French language versions of these tables, Error.FRA and ActionTe.FRA, are located in the Intl folder of the Windows Installer SDK.

You may use the table editor Orca or the utility Msidb.exe provided with the SDK to import the French versions of these tables into the database.

An example of using MsiDatabaseImport and the Import Method of the Database object is provided in the Windows Installer SDK as the utility WiImport.vbs. The following snippet, Imp.vbs, also illustrates the use of the Import method and is for use with Windows Scripting Host.

'Imp.vbs. Argument(0) is the original database. Argument(1) is the
'    path of the folder containing the file to be imported. Argument(2) is the name of the file to be imported.
'
Option Explicit

' Connect to Windows Installer object
On Error Resume Next
Dim installer : Set installer = Wscript.CreateObject("WindowsInstaller.Installer")
Dim databasePath : databasePath = Wscript.Arguments(0)
Dim folder : folder = Wscript.Arguments(1)

' Open database and process file
Dim database : Set database = installer.OpenDatabase(databasePath, 1)
Dim table : table = Wscript.Arguments(2)
database.Import folder, table

' Commit database changes
database.Commit 'commit changes
Wscript.Quit 0

To import and replace the Error table with Error.FRA you may use a command line such as the following.

Cscript Imp.vbs MNPFren.msi C:\Note_Installer\French Error.FRA

To import and replace the ActionText table with ActionTe.FRA you may use a command line such as the following.

Cscript Imp.vbs MNPFren.msi C:\Note_Installer\French ActionTe.FRA

Rerun validation on MNPFren.msi as described in Validating an Installation Upgrade. Note that you may need to modify the column widths of the Error Table to pass validation when using the Windows Installer version 1.1 SDK.

Continue


Localizing Database Columns

Modify any of the other localizable columns in the MNPFren.msi database using a table editor such as Orca or SQL queries. To determine which columns of a particular table may be localized to another language, see the reference topic for that database table. See Database Tables for a list of all database tables.

For example, the Text field of some records in the Control Table may need to be localized into French. The string "Are you sure you want to cancel [ProductName] installation?" in the Cancel Dialog may be modified in this table to be displayed in French. The original record in .msi file appears as follows.

Control Table (partial) of the original .msi file

Dialog_ | Control | Type | X | Y | Width | Height | Attributes | Property | Text | Control_Next | Help
CancelDlg | Text | Text | 48 | 15 | 194 | 30 | 3 |  | Are you sure you want to cancel [ProductName] installation? |  |

You may use a table editor to modify the Text field, such as the Orca table editor provided with the SDK or another table editor, or use a SQL query to change the Text field of the Control table record. An example demonstrating script-driven database queries is provided in the Windows Installer SDK as the utility WiRunSQL.vbs. Use the following command line to modify the field with WiRunSQL.vbs and the Windows Scripting Host. See also Examples of Database Queries Using SQL and Script.

Cscript WiRunSQL.vbs MNPFren.msi "UPDATE Control SET Control.Text='Êtes-vous sûr de vouloir annuler l'installation de [ProductName]?' WHERE Control.Dialog_='CancelDlg' AND Control.Control='Text'"

Control Table (partial) in MNPFren.msi

Dialog_ | Control | Type | X | Y | Width | Height | Attributes | Property | Text | Control_Next | Help
CancelDlg | Text | Text | 48 | 15 | 194 | 30 | 3 |  | Êtes-vous sûr de vouloir annuler l'installation de [ProductName]? |  |

If the installation of MNPFren.msi is canceled by the user, the Cancel Dialog appears displaying the text: "Êtes-vous sûr de vouloir annuler l'installation de MNP2000?"

Continue


Updating ProductLanguage and ProductCode Properties

The ProductLanguage property must be updated to the numeric language identifier (LANGID) for the new language. In the case of the localization example, the value of the ProductLanguage property must be changed from the LANGID for English (1033) to the LANGID for French (1036) in the Property Table.

The value of the ProductCode property in the Property Table must be changed to a new, unique value when localizing a database because a localized product is considered a different product. For example, the German and English versions of an application are considered two different products and must have different product codes. See Product Codes.

Use your database table editor to update the values of the ProductCode and ProductLanguage properties in the Property table. Do not reuse the GUID shown if you copy this example.

Property Table

Property | Value
ProductCode | {EE389960-E426-4EEA-B669-AD8129249881}
ProductLanguage | 1036

Continue


Updating a Summary Information Stream

The value of the Revision Number Summary Property in the summary information stream must be changed to a new, unique value when localizing a database, because the installation database is being changed. See Package Codes.

The value of the Template Summary Property in the summary information stream must be changed to the numeric language identifier (LANGID) of the new language.

If the descriptive text strings in the summary information stream are localized to the new language, the Codepage Summary Property must be set to the correct code page for the new language.

You may modify the summary information stream of the localized package by the same procedure as in Adding Summary Information. An example demonstrating the use of the database summary information methods is also provided in the Windows Installer SDK as the utility WiRunSQL.vbs.

Continue


Adding Localized Resources

Depending upon the application, localization may require modifying or adding resources such as files or registry keys. The localization of the sample application MNP2000 requires adding one additional file to the package, Fre.txt, and the French versions of two existing files: Help.txt and Readme.txt.

The best practice in this case is to localize the package such that the English and French versions can safely coexist on the computer. This includes never installing two different files with identical filenames into the same directory. Because Help.txt and Readme.txt have identical filenames in the two language versions, the French package should install these files into a different directory than the English.

The French package installs Help.txt into a new subdirectory of the RedPark folder, French. Because the addition of Fre.txt adds a resource to the original Help component, the component code for the Help component must be different in the French and English packages. See the rules for component codes in Changing the Component Code.

The French package installs Readme.txt into the directory French so that this filename cannot conflict with the English version. The file Readme.txt is installed with the Notepad component, but the component rules do not require changing the component code. In this example, the component code of Notepad should not be change because RedPark.exe, the registry values specified in the Registry Table, are shared by both language versions. See Adding Registry Information.

Remove the English versions of Help.txt and Readme.txt from the source files and add the new French versions of Help.txt, Readme.txt, and Fre.txt. The localized package should map the installation of files from source to target as follows.

File | Description | Path to source | Path to target
Redpark.exe | Text editor executable file. | C:\Sample\Notepad\Redpark.exe | [ProgramFilesFolder]\Red_Park\French\Redpark.exe
Readme.txt | An informational file. | C:\Sample\Notepad\Readme.txt | [ProgramFilesFolder]\Red_Park\French\Readme.txt
Help.txt | Help manual | C:\Sample\Notepad\Help.txt | [ProgramFilesFolder]\Red_Park\French\Help.txt
Fre.txt | Phone list | C:\Sample\Notepad\Fre.txt | [ProgramFilesFolder]\Red_Park\French\Fre.txt

Use the database editor Orca that is provided with the SDK, or another editor, to open the Directory Table and add a record for the installation of the new directory, French.

Directory Table

Directory | Directory_Parent | DefaultDir
TARGETDIR |  | SourceDir
ProgramFilesFolder | TARGETDIR | .
ARTSDIR | NOTEPADDIR | Arts:Events
HOLDIR | MONDIR | .:Holidays
MENUDIR | NOTEPADDIR | Menu
MONDIR | NOTEPADDIR | Gate
NOTEPADDIR | ProgramFilesFolder | Red_Park:Notepad
SPORTDIR | NOTEPADDIR | Sports:Events
FRENCHDIR | NOTEPADDIR | French:.

Use your table editor to change the ComponentId of the Help component in MNPFren.msi to a new GUID.

Component Table

Component | ComponentId | Directory_ | Attributes | Condition | Keypath
Baseball | {F54ABAC0-33F2-11D3-91D7-00C04FD70856} | SPORTDIR | 2 |  | Baseball.txt
Concert | {76FA7A80-33F6-11D3-91D8-00C04FD70856} | ARTSDIR | 2 |  | Concert.txt
Dance | {CCF834A1-33F8-11D3-91D8-00C04FD70856} | ARTSDIR | 2 |  | Dance.txt
Football | {CCF834A0-33F8-11D3-91D8-00C04FD70856} | SPORTDIR | 2 |  | Football.txt
Help | {9ED21229-FE3C-4FE9-B01D-57E00224FD0B} | NOTEPADDIR | 2 |  | Help.txt
January | {CF0BC690-33C9-11D3-91D6-00C04FD70856} | MONDIR | 2 |  | January.txt
NewYears | {A42D9140-33D8-11D3-91D6-00C04FD70856} | HOLDIR | 2 |  | NewYears.txt
Notepad | {19BED232-30AB-11D3-91D3-00C04FD70856} | FRENCHDIR | 2 |  | Redpark.exe

Use your table editor to add Fre.txt to the File table of MNPFren.msi. Enter the LANGID for French into the Language field for the localized files. All other things being equal, if the file being installed has a different language than the file on the machine, the installer favors the file with the language that matches the product being installed. Language neutral files are treated as just another language so the product being installed is favored again. For more information, see File Versioning Rules.

File Table

File | Component_ | FileName | FileSize | Version | Language | Attributes | Sequence
Baseball.txt | Baseball | Baseball.txt | 1000 |  |  | 0 | 1
Concert.txt | Concert | Concert.txt | 1000 |  |  | 0 | 1
Dance.txt | Dance | Dance.txt | 1000 |  |  | 0 | 1
Football.txt | Football | Football.txt | 1000 |  |  | 0 | 1
Help.txt | Help | Help.txt | 1000 |  | 1036 | 0 | 1
January.txt | January | January.txt | 1000 |  |  | 0 | 1
NewYears.txt | NewYears | NewYears.txt | 1000 |  |  | 0 | 1
Redpark.exe | Notepad | Redpark.exe | 45328 |  |  | 0 | 1
Readme.txt | Notepad | Readme.txt | 1000 |  | 1036 | 0 | 1
Fre.txt | Help | Fre.txt | 1000 |  | 1036 | 0 | 1

This completes the sample localization.


A URL-Based Windows Installer Installation Example

[This is preliminary documentation and subject to change.]

This example illustrates how to create a URL-based installation of a Windows Installer package. The sample requires Windows Installer version 1.5 or later.

To reproduce this sample you need the Signcode.exe utility. For details, see the CryptoAPI Tools Reference in the Platform SDK. You also need Msistuff.exe and Setup.exe utilities from the Platform SDK Components for Windows Installer Developers. For more information, see Internet Download Bootstrapping.

The example has the following specifications:

  • When users visit your Web site and click on the "MySetup Installation" link, they are presented with the option to save or run from that location. If the user selects to run from that location, the Setup.exe upgrades the version of the Windows Installer on their computer, if necessary, verifies the digital signature on the Windows installer package, and installs the package on their computer.
  • There is a digital certificate, Mycert.cer, provided with a private key, Mycert.pvk.
  • The URL of the hypothetical Web site a customer would visit to install the package is http://www.example.com/Products/MySetup/mysetup.html.
  • The Web server layout is as follows.
    URL | File | Description
    http://www.example.com/Products/MySetup/ | Setup.exe | Setup.exe bootstrapper.
    http://www.example.com/Products/MySetup/ | MySetup.msi | Installation package
    http://www.example.com/Products/MySetup/ | Cab1.cab | Source file cabinet #1
    http://www.example.com/Products/MySetup/ | Cab2.cab | Source file cabinet #2
    http://www.example.com/Products/Common/InstMsi/Ansi | Instmsi.exe | ANSI Windows Installer 1.5 redistributable.
    http://www.example.com/Products/Common/InstMsi/Unicode | Instmsi.exe | Unicode Windows Installer 1.5 redistributable.

Continue


Configuring the Setup.exe Resources

[This is preliminary documentation and subject to change.]

Starting with Windows Installer version 1.5, a configurable bootstrap executable (Setup.exe) and configuration tool (Msistuff.exe) is included in the Platform SDK Components for Windows Installer Developers. By using Msistuff.exe to configure the resources in Setup.exe, developers can easily create a Web installation of a Windows Installer package. For more information see Internet Download Bootstrapping.

Entering the following command line configures the resources for the sample described in A URL Based Windows Installer Installation Example.

MsiStuff setup.exe /u http://www.example.com/Products/MySetup /d
MySetup.msi /n MySetup /v 150 /i http://www.example.com/Products/Common/InstMsi /a Ansi/Instmsi.exe
/w Unicode/Instmsi.exe

Continue


Sign Setup.exe and MySetup.msi

[This is preliminary documentation and subject to change.]

Before you place Setup.exe and MySetup.msi on the Web server, you should sign the files with your digital certificate and private key, Mycert.cer and Mycert.pvk, using the Signcode.exe utility. For more information about using the SignCode utility, see CryptoAPI Tools Reference in the Platform SDK. Signing the package requires Windows Installer version 1.5.

Continue


Establish an HTML Reference to Setup.exe

[This is preliminary documentation and subject to change.]

The final step is to place a reference to the Setup.exe on the hypothetical MySetup Web page (MySetup.html) described in A URL Based Windows Installer Installation Example. Use the following HTML script:

<a href="http://www.example.com/Products/MySetup/setup.exe">MySetup Installation</a>

Clicking on the "MySetup Installation" link presents users with the option to save or run from that location. If the user selects run from that location, the Setup.exe upgrades the version of the Windows Installer on the computer, if necessary, verifies the digital signature on the Windows installer package, and installs the package on their computer.

This completes the example.


Glossary

A B C D E F G I M P Q R S T U V W


A

accessibility
Design practice for making the installer's user interface accessible to all users. For more information about accessibility, see the overview topic: Accessibility.
acquisition phase
The phase of the installation during which the installer determines the installation procedure. It begins when an application or user instructs the Windows Installer to install an application or feature. The installer then queries the database for information as it generates the execution script for the installation. For more information about the phases of an installation, see Installation Mechanism.
action
Many of the functions performed by the Windows Installer are encapsulated into actions. Each action specifies the execution of a particular function and the total procedural flow of the installation is prescribed by the sequence of actions in the sequence tables. Standard actions are built into the Windows Installer and custom actions are written by the author of the installation package.
advertising
The capability of the installer to make the interfaces required for loading and making an application available without installing the application. When a user or application activates an advertised interface the installer then proceeds to install the necessary components. The two types of advertising are assigning and publishing. See also install-on-demand. For more information about how the installer advertises applications, see Advertisement.
assigning
Assigning makes an application available, and appear as if it has been installed to a user, without actually installing it. Assigning adds shortcuts and icons to the Start menu, associates the appropriate files, and writes the registry entries for the application. If a user tries to open an assigned application, the installer then installs the files of the application. Assigning and publishing are two methods of advertising. For more information about how the installer advertises applications, see Advertisement.
asynchronous execution
During an asynchronous execution of a custom action the installer runs the separate threads of the custom action and the current installation simultaneously. For more information, see the overview topic: Synchronous and Asynchronous Custom Actions.


B

basic UI
A level of the installer's internal user interface capabilities. The basic UI level supports a user interface for the installation that has simple progress and error handling. For more information about user interface levels, see User Interface Levels.


C

cabinet file
A cabinet is a single file, usually with a .cab extension, that stores compressed files in a file library. The cabinet format is an efficient way to package multiple files because compression is performed across file boundaries, significantly improving the compression ratio. For information about creating cabinets, see Cabinet Files.
checksum
A computed value that depends on the contents of a file and is stored with the data to detect corruption of the file's data. The system checks this value to provide confidence that the data is uncorrupted.
component
The smallest piece of an installation handled by the installer, also a building-block of an application or feature from the programmer's perspective. Examples of components are a group of related files, a COM object, or a library. For more information about components, see Components and Features.
committing databases
Changes made in a database are accumulated and are not reflected in the actual database until you commit the database. For more information, see Committing Databases.
ControlEvent
A part of the functionality of the installer's user interface. A typical ControlEvent triggers some action by the installer upon the activation of a dialog box control or some other event. For more information about using ControlEvents, see ControlEvent Overview.
costing
Costing is the method used by Microsoft Windows Installer to determine the disk space required by all the components in an installation. Costing takes into account factors such as whether existing files need to be overwritten. For more information about costing, see File Costing.
.cub file
A .cub file is a validation module that stores and provides access to ICE custom actions. See Sample .cub File. See also Windows Installer File Extensions.
custom action
An action that is written by the author of the package and that is not built into the installer as a standard action. For more information about custom actions, see Custom Actions.


D

database function
A function that accesses the installer database. These functions are provided primarily for use by installer package authoring tools and they are not intended to be used to call installer services. For more information see the chapter Database Functions. For more information about functions used to call installer services see the Installer Function Reference.
database handle
Before working with a database you must first obtain a handle to it. See Obtaining a Database Handle.


E

execution phase
The installation phase during which the installer executes a script of installer actions. Using Microsoft® Windows® 2000 this processing is performed by the installer service. In the case of a managed application the script is executed with system privileges. For more information about the phases of an installation, see Installation Mechanism.
execution script
The execution script of installer actions for the installation. The execution script is generated during the acquisition phase of the installation and executed during the execution phase. For more information, see the topic: Installation Mechanism.
external source files
Source files of the application being installed that are stored outside of the .msi file. Multiple external source files can be compressed and stored together inside of a cabinet file included in the package.
external user interface
A user interface provided by the author of an installation package that does not use the internal user interface capabilities of the installer. For more information, see About The User Interface.


F

feature
Specific functionality of an application as seen from the user's perspective. See Components and Features.
full UI
A level of the installer's internal user interface capabilities. The full UI level supports a user interface for the installation, including dialog boxes, progress bars, and error messages. For more information, see User Interface Levels.


G

globally unique identifier
A globally unique identifier, or GUID, is a data type representing a Class Identifier. For more information about the restrictions on authoring GUIDs, see GUID.
GUID
See globally unique identifier.


I

IAT
See import address table.
.idt file
An .idt file is an exported installer database table. See Importing and Exporting and Windows Installer File Extensions.
import address table
The location where the computed virtual address from each function that is imported from all DLLs is saved.
internal user interface
The built-in capabilities of the installer that can be used to author a graphical user interface for the installation process. An author may alternatively choose using an external user interface. For more information, see About The User Interface.
install level
For any installation, there is a specified install level value. An application is installed only if its own level is less than or equal to the install level. The set of applications chosen for installation can therefore be changed by altering the install level. For more information about the install level, see the discussion at Feature table.
installation-on-demand
An installer service that installs applications or features only when they are requested by the user or another application. Advertising makes a feature or application available for install-on-demand installation. For more information, see: Installation-On-Demand.
installer
The Microsoft Windows Installer.
installer database
A relational database containing all the setup instructions for an installation. The installer database is stored in the .msi file. For more information about the installer database, see Installer Database.
installer function
A function called by a user or application to obtain installer services and functionality. This is the application programming interface of the installer. For information about installer functions, see Installer Function Reference.
installer package authoring tool
Software that enables a developer to create and edit an .msi file. This together with any external source files comprise a package containing all the information required for an installation.
internal source files
Source files for the application being installed that are stored in the .msi file. Multiple internal source files can be compressed and stored together in a cabinet file that is stored within an .msi file.


M

managed application
An application is a "managed application" if system (i.e. elevated) privileges are used to install the application. An application will be managed on a system if it is a per-machine installation on Windows NT 4.0 or Windows 2000 or if the application is assigned or published using Group Policy on Windows 2000.
merge
A merge combines the information in two installation databases to form a single resultant database. See Merging Databases.
merge module
A merge module is a database merged with an installation package to deliver new components to an application. Merge modules cannot be installed alone. See Merge Modules.
Microsoft Windows Installer
Client side installer service for managing the installation of applications on 32-bit platforms. The application must be encapsulated in a package. See About Windows Installer.
.msi file
An .msi file is a COM-structured storage file containing the instructions and data required to install an application. Every package contains at least one .msi file. The .msi file contains the installer database, a summary information stream, and possibly one or more transforms and internal source files. See Windows Installer File Extensions.
.msm file
A .msm file is a merge module. See also Windows Installer File Extensions.
.msp file
A .msp file is a patch package. See Windows Installer File Extensions.
.mst file
An .mst file is a transform package. See Merges and Transforms. See Windows Installer File Extensions.


P

package
A package consists of an .msi file and any external source files that may be pointed to by this file. A package therefore contains all the information the Microsoft Windows Installer needs to run the user interface and to install or uninstall the application. See also installer database.
package code
A package code is a GUID that identifies a particular package. A unique package code is required because some transforms or patch packages can be applied to more than one application or can upgrade an application into another application or version. See Package Codes.
patching
Patching is a method of updating a file that replaces only the bits being changed, rather than the entire file. This means that users can download an upgrade patch for a product that is much smaller than the entire product. See Patch Packages.
patch file
A patch package used for patching. See Patching and Upgrades.
preview mode
The installer provides a basic preview mode for viewing the design of the user interface. For more information about the preview mode, see Previewing the User Interface.
progress bar
A control the installer can display during script execution time representing the time progress of the installation. See Authoring a Progress Bar Control.
property
Properties are global variables used during an installation. (See About Properties.)

The term "property" also refers to an attribute of an automation object. (See Automation Interface.)

publishing
Publishing and assigning are methods of advertising a feature or application. Publishing does not populate the user interface. However, if an another application attempts to open a published application, there is enough information present for the installer to assign the published application. See also assigning. For more information, see Components and Features.


Q

qualified component
A qualified component is similar to a pointer in that it is a method of single-level indirection. Qualified components are primarily used to group components with parallel functionality into categories. See Qualified Components.


R

reduced UI
A level of the installer's internal user interface capabilities. Displays only authored modeless dialog boxes. For more information, see User Interface Levels.
reinstall
A partial or complete reinstallation of an installed application. Commonly done to repair an application if any files or registry entries have become corrupted or are missing. See Reinstalling a Feature or Application.
resiliency
The capability of an application to recover gracefully from errors without presenting the user with error messages. For more information about how the installer service improves resiliency, see Resiliency.
rollback
The automatic restoration of the original state of the computer should the installation be unsuccessful. See Rollback Installation (Windows Installer).


S

sequence tables
Tables in the installer database that list actions in a sequence and specify the flow of the installation. For more information, see Using a Sequence Table.
source list
Specifies the locations where the installer is to search for external source files.
standard action
A built-in action of the Windows Installer. For more information, see Standard Actions.
SQL
Acronym for Structured Query Language.
Structured Query Language
Structured Query Language (SQL) is a language used to interrogate and process data in a relational database. You can use SQL to make queries to the installer database. See Working with Queries.
summary information stream
A storage location in the .msi file for information that can be viewed with Microsoft® Windows® Explorer. For more information about summary information, see About the Summary Information Stream.
synchronous execution
Synchronous execution of a custom action means that the installer waits for the separate thread of a custom action to complete before continuing the thread of the current installation. See Synchronous and Asynchronous Custom Actions
system policy
System administrators can use system policies to control user and computer configurations from a single location on a network. System policies propagate registry settings to a large number of machine without requiring the administrator to have detailed knowledge of the registry The system policy of the installer can be configured using the Group Policy Editor (GPE), included in Windows NT®/Windows® 2000. For more information see System Policy.


T

transform
A transform is a template of the differences between two installer databases that can be applied to produce similar changes in other databases. For example, a localization transform can be used to change the language of an application. For more information, see Merges and Transforms.
transform error condition flags
A set of properties used to flag the error conditions of a transform. See MsiCreateTransformSummaryInfo.
transform validation flags
A set of properties used to verify that the transform can be applied to the database. For a list of these properties, see MsiCreateTransformSummaryInfo.


U

upgrade
An upgrade is a more recent and improved version of an existing application. See Patching and Upgrades.


V

volume
A storage medium, such as a disk or tape, that is formatted to contain files and directories.


W

Windows Installer
The Microsoft Windows Installer.


Appendix

For additional information about the Microsoft® Windows® Installer package, see the following:

  • Command Line Options
  • Entity Relationship Diagram Legend
  • Uninstall Registry Key
  • _MsiExecute Mutex
  • __MsiPromptForCD Mutex
  • Windows Installer File Extensions
  • Table Names
  • Platform Support of Advertisement
  • OLE Limitations on Streams
  • Bootstrapping
  • Internet Download Bootstrapping
  • Resolving Advertised Shortcuts with IShellLink::Resolve
  • Passing Null as the Argument of Windows Installer Functions
  • Operating System Property Values
  • Platform SDK Components for Windows Installer Developers
  • Released Versions of Windows Installer
  • Windows Installer Development Tools
  • Windows Installer and Logo Requirements
  • Windows Installer Error Messages
  • Error Codes


Command Line Options

The executable program that interprets packages and installs products is Msiexec.exe. Note that Msiexec also sets an error level on return that corresponds to the Microsoft® Win32® error codes. The following table describes the command-line options for this program.

Option | Parameters | Meaning
/I | Package|ProductCode | Installs or configures a product.
/f | [p|o|e|d|c|a|u|m|s|v] Package|ProductCode | Repairs a product. This option ignores any property values entered on the command line. The default argument list for this option is 'pecms'. This option shares the same argument list as the REINSTALLMODE property. p - Reinstall only if file is missing o - Reinstall if file is missing or if an older version is installed. e - Reinstall if file is missing or an equal or older version is installed. d - Reinstall if file is missing or a different version is installed. c - Reinstall if file is missing or the stored checksum doesn't match the calculated value. Only repairs files that have msidbFileAttributesChecksum in the Attributes column of the File table. a - Force all files to be reinstalled. u - Rewrite all required user specific registry entries. m - Rewrite all required machine specific registry entries. s - Overwrite all existing shortcuts. v - Run from source and re-cache the local package.
/a | Package | Administrative installation option. Installs a product on the network.
/x | Package|ProductCode | Uninstalls a product.
/j | [u|m]Package or [u|m]Package /t Transform List or [u|m]Package /g LanguageID | Advertises a product. This option ignores any property values entered on the command line. u - Advertise to the current user. m - Advertise to all users of machine. g - Language ID t - Applies transform to advertised package.
/L | [i|w|e|a|r|u|c|m|o|p|v|+|!]Logfile | Specifies path to log file and the flags indicate which information to log. i - Status messages w - Non-fatal warnings e - All error messages a - Start up of actions r - Action-specific records u - User requests c - Initial UI parameters m - Out-of-memory or fatal exit information o - Out-of-disk-space messages p - Terminal properties v - Verbose output + - Append to existing file ! - Flush each line to the log "*" - Wildcard, log all information except for the v option. To include the v option, specify "/l*v".
/m | filename | Generates an SMS status .mif file. Must be used with either the install (-i), remove (-x), administrative installation (-a), or reinstall (-f) options. The ISMIF32.DLL is installed as part of SMS and must be on the path. The fields of the status mif file are filled with the following information: Manufacturer - Author Product - Revision Number Version - Subject Locale - Template Serial Number - not set Installation - set by ISMIF32.DLL to "DateTime" InstallStatus - "Success" or "Failed" Description - Error messages in the following order: 1) Error messages generated by installer. 2) Resource from Msi.dll if install could not commence or user exit. 3) System error message file. 4) Formatted message: "Installer error %i", where %i is error returned from Msi.dll
/p | PatchPackage | Applies a patch. To apply a patch to an installed administrative image you must combine options as follows: /p <PatchPackage> /a <Package>
/q | n|b|r|f | Sets user interface level. q , qn - No UI qb - Basic UI qr - Reduced UI with a modal dialog box displayed at the end of the installation. qf - Full UI with a modal dialog box displayed at the end. qn+ - No UI except for a modal dialog box displayed at the end. qb+ - Basic UI with a modal dialog box displayed at the end. The modal box is not displayed if the user cancels the installation. qb- - Basic UI with no modal dialog boxes. Please note that /qb+- is not a supported UI level.
/? or /h |  | Displays copyright information for the Windows Installer.
/y | module | Calls the system API DllRegisterServer to self-register modules passed in on the command line. For example, msiexec /y my_file.dll. This option is only used for registry information that can't be added using the registry tables of the .msi file.
/z | module | Calls the system API DllUnRegisterServer to unregister modules passed in on the command line. For example, msiexec /z my_file.dll. This option is only used for registry information that can't be removed using the registry tables of the .msi file.

The options /i, /x, /f[p|o|e|d|c|a|u|m|s|v], /j[u|m], /a, /p, /y and /z should not be used together. The one exception to this rule is that patching an administrative installation requires using both /p and /a. The options /t and /g should only be used with /j. The options /l and /q can be used with /i, /x, /f[p|o|e|d|c|a|u|m|s|v], /j[u|m], /a, and /p.

To install a product from A:\Example.msi, install the product as follows:

msiexec /i A:\Example.msi

Only public properties can be modified using the command line. All property names on the command line are interpreted as uppercase but the value retains case sensitivity. If you enter MyProperty at a command line, the installer overrides the value of MYPROPERTY and not the value of MyProperty in the Property table. For more information, see About Properties.

To install a product with PROPERTY set to VALUE use the following syntax on the command line. You can put the property anywhere except between an option and its argument.

Correct syntax:

msiexec /i A:\Example.msi PROPERTY=VALUE

Incorrect syntax:

msiexec /i PROPERTY=VALUE A:\Example.msi

Property values that are literal strings must be enclosed in quotation marks. Include any white spaces in the string between these marks.

msiexec /i A:\Example.msi PROPERTY="Embedded White Space"

To clear a public property using the command line, set its value to an empty string.

msiexec /i A:\Example.msi PROPERTY=""

For sections of text set apart by literal quotation marks, enclose the section with a second pair of quotation marks.

msiexec /i A:\Example.msi PROPERTY="Embedded ""Quotes"" White Space"

The following is an example of a complicated command line.

msiexec /i testdb.msi INSTALLLEVEL=3 /l* msi.log COMPANYNAME="Acme ""Widgets"" and ""Gizmos."""

The following example illustrates advertisement options. Note that switches are not case-sensitive.

msiexec /JM msisample.msi /T transform.mst /LIME logfile.txt


Entity Relationship Diagram Legend

A black circle leading to an open diamond indicates a one-to-many relationship between the primary key of the first table and the foreign key of the second table. For an example of this look at the figure for the Registry Tables Group. Extension is a primary key of the Extension table and a foreign key of the Verb table. One Extension can therefore can be registered to have several Verbs, but a particular Verb can only be associated to one Extension.


Uninstall Registry Key

The following installer properties give the values written under the registry key:

HKEY_LOCAL_MACHINE\Software\Microsoft\Windows\CurrentVersion\Uninstall

Value | Windows installer property
INSTALLPROPERTY_INSTALLEDPRODUCTNAME | ProductName Property
INSTALLPROPERTY_VERSIONSTRING | Derived from ProductVersion Property
INSTALLPROPERTY_HELPLINK | ARPHELPLINK Property
INSTALLPROPERTY_HELPTELEPHONE | ARPHELPTELEPHONE Property
INSTALLPROPERTY_INSTALLLOCATION | ARPINSTALLLOCATION Property
INSTALLPROPERTY_INSTALLSOURCE | SourceDir Property
INSTALLPROPERTY_INSTALLDATE | Dynamically determined installation date.
INSTALLPROPERTY_PUBLISHER | Manufacturer Property
INSTALLPROPERTY_LOCALPACKAGE | Dynamically determined name of the cached package.
INSTALLPROPERTY_URLINFOABOUT | ARPURLINFOABOUT Property
INSTALLPROPERTY_URLUPDATEINFO | ARPURLUPDATEINFO Property
INSTALLPROPERTY_VERSIONMINOR | Derived from ProductVersion Property
INSTALLPROPERTY_VERSIONMAJOR | Derived from ProductVersion Property
INSTALLPROPERTY_PACKAGECODE | Revision Number Summary Property in the Summary Information Stream.
INSTALLPROPERTY_VERSION | Derived from ProductVersion Property

The ARPCOMMENTS property, ARPCONTACT property, ARPPRODUCTICON property, and ARPREADME property provide the Add/Remove Control Panel Comments, Contact, and ReadMe written under the Uninstall Registry Key.


_MSIExecute Mutex

The _MSIExecute mutex is set only while processing the InstallExecuteSequence table, AdminExecuteSequence table or AdvtExecuteSequence table.

Because two installations cannot be run in the same process, an attempt to call the installer's application programming interface (API) returns ERROR_INSTALL_ALREADY_RUNNING in two cases:

  • While the _MSIExecute mutex is set.
  • While the current process is processing the InstallUISequence table or AdminUISequence table.


__MsiPromptForCD Mutex

The __MsiPromptForCD mutex exists whenever the installer is prompting the user to insert a CD-ROM. Autoplay programs should check that the __MsiPromptForCD mutex is not currently set before starting. Note that it is possible for a prompt for a CD-ROM to occur before either the InProgress key or the _MSIExecute mutex exist.


Windows Installer File Extensions

The following file name extensions are used with the Microsoft® Windows® Installer.

Extension | Description
.msi | Windows Installer Database.
.msm | Windows Installer Merge Module.
.msp | Windows Installer Patch.
.mst | Windows Installer Transform.
.idt | Exported Windows Installer Database Table.
.cub | Validation module.
.pcp | Windows Installer Patch Creation File

See Also

Installation Package, Merge Modules, Patch Packages, Transforms, Importing and Exporting, Sample .CUB File


Table Names

Table names are limited to 31 characters. If a table name contains a period (a practice that is permitted but not recommended), the name must be enclosed within grave accent marks ` (ASCII value 96), for example, `moo.goo`. This escape syntax prevents clashes between the table name and reserved words, such as SQL keywords. For more information, see SQL Syntax.


Platform Support of Advertisement

Microsoft® Windows® Installer supports advertisement of applications and features according to operating system. The following outlines advertisement support on different platforms.

Platform | Advertisement support
Microsoft® Windows® 2000 | Shortcuts and their icons. Extensions and their icons specified in the ProgId Table. Shell and command Verbs registered underneath the ProgId key. CLSID contexts and InProcHandler. Install-On-Demand through OLE is only available programmatically through CoCreateInstance (C/C++) and CreateObject or GetObject (Visual Basic). NOTE: AppId and Typelib information is only written when an advertised component is installed.
Microsoft Windows® 98 | Shell and MIME support. All of the above except CLSID, which is only written when installing an advertised component.
Microsoft Windows® 95 and Windows NT® 4.0 + IE4.01 sp1 + Windows Desktop Update (shell32.DLL >= 4.72.3110.0) | Shell and MIME support. All of the above except CLSID, which is only written when installing an advertised component.
Windows 95 and Windows NT 4.0 (shell32.DLL < 4.72.3110.0) | Advertisement is not supported by this platform.


OLE Limitations on Streams

Developers of installation databases need to be aware of two limitations on the handling of streams by the Win32 OLE structured storage implementation. These limitations can affect installer functions indirectly through transforms and other data that may be stored in the database as a stream.

There are two relevant limitations:

  • Binary data is stored with an index name created by concatenating the table name and the values of the record's primary keys using a period delimiter. The first 64 characters of the index name must be unique. Note that double-byte characters count as 2.
  • Although you can have multiple streams open at one time, you cannot open a stream a second time until the first reference is closed. This means you cannot select the same binary data stream to be open in multiple records simultaneously. Attempts to read the binary data from the second record fail. Also you cannot rename the primary keys of a record while a binary data stream in that record is open.


Bootstrapping

Currently every installation that attempts to use the Microsoft® Windows® Installer begins by checking whether the installer is present on the user's computer, and if it is not present, whether the user and computer are ready to install Windows Installer. A setup application Instmsi.exe is available with the Windows Installer SDK that contains all logic and functionality to install Windows Installer. However, a bootstrapping application must manage this installation.

The bootstrapping application must first check to see whether Windows Installer is currently installed. If Windows Installer is not currently installed, the bootstrapping application must query the operating system to determine which version of the Instmsi.exe is required. Once the installation of Windows Installer has initiated, the bootstrapping application must handle return codes from the Instmsi.exe application and handle any reboots that are incurred during the Windows Installer installation.

The following example demonstrates how the setup application which installs Microsoft® Office 2000 checks the user's system and configures the Windows Installer installation. This example is specifically written to install Office 2000 and should be used as a general reference only.

When a user inserts an Office 2000 CD-ROM into their computer, Setup.exe attempts to launch the maintenance mode, the setup application, or does nothing at all, according to the user's needs. The following section describes how the Office 2000 setup application, named Setup.exe, qualifies the user and their computer, constructs a command line and installs Windows Installer using the Msiexec.exe application.

How Setup.exe Bootstraps the Windows Installer when Installing Office 2000

  1. The user inserts an Office 2000 CD-ROM into their computer. The Windows operating system initiates Setup.exe using the /autorun switch and the Autorun.inf file. The Autorun.inf file is found at the root of the Office 2000 CD-ROM and contains the following sections:

    [Autorun]
    [Office Features]
    [Product Information]
    [ServicePack].

    The [Autorun] section contains a command line that executes the Setup.exe application, executes the icon used to display the disc, and contains information to add an "Install" option and a "Configure" option to the context menu for the CD-ROM.

    The [Office Features] section contains a list of features and feature name pairs.

    The [Product Information] section specifies the name and version of the application.

    The [ServicePack] section allows a network administrator to set the minimum required service pack level. The network administrator can use this section to author the text of an alert message displayed if the local operating system does not have the required service pack.

    The following is a sample Autorun.inf.

    [autorun]
OPEN=setup.EXE /AUTORUN /KEY:Software\Microsoft\Office\9.0\Common\General\InstallProductID
ICON=setup.EXE,1
shell\configure=&Configure
shell\configure\command=setup.EXE
shell\install=&Install
shell\install\command=setup.EXE
[OfficeFeatures]
Feature1=ACCESSFiles
Feature2=OfficeFiles
Feature3=WORDFiles
Feature4=EXCELFiles
Feature5=PPTFiles
[ProductInformation]
DisplayName=Microsoft Office 9
Version=9.0
ProductCode={product guid}
[ServicePack]
MessageText="Office 2000 requires Windows NT 4.0 Service Pack 3 for NT to install. Please download this from www.microsoft.com prior to installing Office."
SPLevel=3
  2. The Setup.exe application checks for the _MsiPromptForCD mutex. Windows Installer creates this mutex when it prompts the user to insert the CD-ROM. The presence of the mutex indicates that Windows Installer is running an installation that has requested the Office 2000 CD-ROM. In this case, the Setup.exe application exits immediately and allows the Office 2000 installation to continue. If the mutex is absent, the Setup.exe application continues at step 3 where a registry key is evaluated to determine if Office 2000 is installed.
  3. The Setup.exe application checks the presence of the Office9 registry key: HKCU/Software/Microsoft/Office/9.0/Common/General/InstallProductID

    If this registry key does not exist, the Setup.exe application continues at step 6 where the operating system is checked to determine if it qualifies for the installation of Office 2000.

  4. If the Office 2000 registry key exists, the Setup.exe application checks the current installation state by calling MsiQueryProductState. A return state of InstallState_Default indicates that Office 2000 is already installed and the Setup.exe application continues at step 5 where the Office 2000 is checked for run from source.

    If Office 2000 is not installed, the Setup.exe application continues at step 6 where the operating system is checked to determine if it qualifies for the installation of Office 2000.

  5. The Setup.exe application calls MsiQueryFeatureState for each of the features in the [OfficeFeatures] section of the Autorun.inf file. If any of these features returns INSTALLSTATE_SOURCE, this indicates that the feature is being run from source and the Setup.exe application exits immediately.

    If none of the features returns INSTALLSTATE_SOURCE, the Setup.exe application launches the installer application, Msiexec.exe, and presents the Windows Installer maintenance mode before exiting.

  6. The Setup.exe application determines whether the operating system qualifies for an installation of Office 2000. Windows® 95 or Windows® 98, Windows NT® 4.0, or Windows® 2000 is required to install Office 2000. If the operating system requires a service pack update to qualify for Office 2000, the Setup.exe application displays the text specified in the Autorun.inf file. If the operating system does not qualify for Office 2000 or an upgrade of Office 2000, the Setup.exe application displays a message that prevents the user from continuing.

    If the operating system qualifies for Office 2000, the Setup.exe application continues at step 7, which determines whether Windows Installer is installed on the user's computer.

  7. If Windows Installer exists on the user's machine, the Setup.exe application launches the Msiexec.exe application and passes the Office 2000 .msi file to it.

    If Windows Installer is not installed on the local machine, the Setup.exe application continues at step 8, which determines whether the operating system qualifies to have Windows Installer installed.

  8. Windows Installer can be installed on Windows NT/Windows 2000, or Windows 95 or Windows 98. Installation on Windows NT/Windows 2000 requires administrative privileges. If the user does not have administrative privileges, the Setup.exe application displays an error message.
  9. If the local computer is eligible to have Windows Installer installed, the Setup.exe application runs the correct version of the Instmsi.exe installer application for the platform. Setup.exe may pass the "/q" command line switch to suppress the user interface and prevent the user from changing any installation configuration options.
  10. The Setup.exe application loads the newly installed Msi.dll file and performs a call to the MsiInstallProduct function to install the user's application..

Setup.exe Command Line Parameters

The Setup.exe application enables administrators and users to pass command line options to the Msiexec.exe application. For more information, see Command Line Options. The following table lists the command options that can be used with Setup.exe.

Option | Usage | Meaning
/autorun | setup.exe /autorun | Runs the Autorun.inf described above.
/a | setup.exe /a | Initiates an administrative installation.
/j | [u|m]Package or [u|m]Package /t Transform List or [u|m]Package /g LanguageID | Advertises a product. This option ignores any property values entered on the command line. u - Advertise to the current user. m - Advertise to all users of machine. g - Language ID t - Applies transform to advertised package.
/i | setup.exe /i Office9.msi /t ProgramMgmt.mst | Specifies the .msi file that Setup.exe is to install. If the /i option is not included, Setup.exe uses the Office9.msi file.
/o<property=value> | setup.exe /o CDKEY=111111-1111 | Sets properties in the .msi file. Setup.exe passes these it to msiexec as written.
/q | setup.exe /q | Set the UI level the installation. /q - no UI (/qn - for msiexec.) /qb - basic UI /qr - reduced UI.
/m# | setup.exe /m4 | Supports multiple licenses in accordance with Select agreements. This property is used in by the License Verification custom action to write the LV certificate. The /m option must be followed by the number of unlocks allowed. The value specified by the /m option should be set as the "M" property in the Office9.msi file. If no value is specified, but the /m option is used with setup, the value of 0 should be set. The /m option is required to support Select customers using a CD or network.
/settings | setup.exe /settings mysettings.ini | Enables administrators to specify an .ini file containing all of the customized settings to be passed during Office 2000 setup. See the description of the .ini file below.

Using an .ini File

Creating an initialization file may be easier than creating a long command line. Using the /settings option, the Setup.exe application reads the specified .ini file and constructs a command line to pass to the Msiexec.exe application. Only properties supported on the command line are supported in the .ini file. If a property or value is found in both the .ini file and on the command line, the command line settings override the .ini file settings.

The format of the .ini file is:

[msi]
[mst]
[options]
[Display]

The [msi] section of the .ini file specifies the path to the installation package for the installation. This corresponds to the /i option on the command line.

The [mst] section of the .ini file specifies the path to transforms used with this installation. This corresponds to the /j option on the command line. Multiple transforms are each indicated on a different line, using MST1 - MST(N). When parsed into the command line, the list in the .ini file is turned from left to right. Note that the number associated with the MST(N) title is present only to maintain unique identifiers and has no programmatic meaning.

The [options] section allows network administrators to set and override properties in the .msi or .mst files. Options set in the .ini file are added to the command line using the /o option. Each option in the option section must have a property name and a value.

The [Display] section is used to set the user interface level used during setup. This corresponds to the /q option on the command line. Valid values are - none, basic, reduced, and full.

Sample .ini file

[MSI]
MSI=\\sourceshare\Office2000\Office2000.msi
[MST]
MST1=\\sourceshare\Office2000\trns1.mst
MST2=\\sourceshare\Office2000\trns2.mst
[Options]
PUBLICPROPERTY=your value

[Display]
Display=None


Internet Download Bootstrapping

[This is preliminary documentation and subject to change.]

Beginning with Windows Installer version 1.5, a configurable bootstrap executable (Setup.exe) and configuration tool (Msistuff.exe) is included in the Platform SDK Components for Windows Installer Developers. By using Msistuff.exe to configure the resources in Setup.exe, developers can easily create a web installation of a Windows Installer package.

The minimum installer version required by the bootstrap executable is Windows Installer version 1.5.

The bootstrap executable provided with the Windows Installer 1.5 SDK does the following:

  • Calls WinVerifyTrust to verify the digital signature of the .msi file. Windows Installer version 1.5 and later versions provides a Subject Interface Package (SIP) to enable signing of Windows Installer packages.
  • If necessary upgrades the version of the Windows Installer on the machine.

The following resources of Setup.exe can be displayed or configured using Msistuff.exe.

Resource ID | Description
ISETUPPROPNAME_BASEURL | The base URL location of Setup.exe. If no value is specified the location of Setup.exe defaults to removable media. Only URL-based installs are subject to a check with WinVerifyTrust. The trailing forward slash on the URL is optional. This resource is optional.
ISETUPPROPNAME_DATABASE | The name of the .msi file. This is a relative path to the .msi file specified relative to the location of the Setup.exe program. This resource is required.
ISETUPPROPNAME_PRODUCTNAME | The name of the product. This is the name used in the banner text in the downloaded user interface. This resource is optional. If omitted, the name defaults to "the product".
ISETUPPROPNAME_MINIMUM_MSI | The minimum version of the Windows Installer required. If the minimum version of the Windows Installer is not installed on the computer, the appropriate Instmsi.exe is called to upgrade the Windows Installer. The value of this property has the same format as the PID_PAGECOUNT value. For more information, see the Page Count Summary Property. This value must be at least 150, the value that identifies the Windows Installer version 1.5. This resource is required.
ISETUPPROPNAME_INSTLOCATION | The base URL location of the Windows Installer upgrade executables. This resource may be omitted. If this value is omitted, the default location of the upgrade executables is the location of Setup.exe.
ISETUPPROPNAME_INSTMSIA | The name of the ANSI version of the Windows Installer upgrade executable. This is a relative path to the ANSI version of Instmsi.exe relative to the location specified by ISETUPPROPNAME_INSTLOCATION. This resource is required.
ISETUPPROPNAME_INSTMSIW | The name of the Unicode version of the Windows Installer upgrade executable. This is a relative path to the Unicode version of Instmsi.exe relative to the location specified by ISETUPPROPNAME_INSTLOCATION. This resource is required.
ISETUPPROPNAME_PROPERTIES | The PROPERTY=VALUE strings. These are the PROPERTY=VALUE pairs to include on the command line. This option is optional.

For example, the following ISETUPPROPNAME_BASEURL and ISETUPPROPNAME_DATABASE values would be used for the following hypothetical package locations.

Actual Package Location | Resource Values
http://www.example.com/Products/Product1/product1.msi | ISETUPPROPNAME_BASEURL = http://www.example.com/Products/Product1 ISETUPPROPNAME_DATABASE = product1.msi
http://www.example.com/Products/Product1/product1.msi | ISETUPPROPNAME_BASEURL = http://www.example.com/Products/Product1 ISETUPPROPNAME_DATABASE = ../Products1/product1.msi
e:\product1.msi | Omit ISETUPPROPNAME_BASEURL. ISETUPPROPNAME_DATABASE = product1.msi
e:\setup\product1.msi (The currently running location of Setup.exe is e:\setup.exe.) | Omit ISETUPPROPNAME_BASEURL. ISETUPPROPNAME_DATABASE = Setup\product1.msi

For more information see also A URL Based Windows Installer Installation Example.


Resolving Advertised Shortcuts with IShellLink::Resolve

In certain cases with Microsoft® Windows® 98 and in the Internet Explorer 4.01 shell, it may be necessary to launch an installation-on-demand of an application by calling the system method IShellLink::Resolve on an advertised shortcut of an application. By default, a call to IShellLink::Resolve on an advertised shortcut does not install the application. To override the default, and allow this type of installation-on-demand, add the name of the executable file as the name portion of a value pair under one or both of the following registry keys.

HKLM\Software\Microsoft\Windows\CurrentVersion\Installer\ResolveIOD

HKCU\Software\Microsoft\Windows\CurrentVersion\Installer\ResolveIOD


Passing Null as the Argument of Windows Installer Functions

Windows Installer functions that return data in a user provided memory location should not be called with NULL as the value for the pointer. These functions return a string or return data as integer pointers, but return inconsistent values when passing NULL as the value for the output argument.

Do not pass Null as the value of the output argument for any of the following functions.

MsiGetProperty

MsiRecordGetString

MsiFormatRecord

MsiGetSourcePath

MsiGetTargetPath

MsiGetFeatureState

MsiViewGetError

MsiSummaryInfoGetProperty

MsiEvaluateCondition

MsiGetFeatureCost

MsiGetFeatureState

MsiGetComponentState

MsiGetFeatureCost

MsiGetFeatureValidStates


Operating System Property Values

The following table gives values for selected Operating System Properties, including Microsoft® Windows® 95, Windows 98, Microsoft Windows NT® version 4.0, and Microsoft Windows 2000.

System | Version9X | VersionNT | WindowsBuild | ServicePackLevel
Windows 95 (Gold) | 400 |  | 950 |
Windows 95 + OSR | 400 |  |  |
Windows 95 + OSR2 | 400 |  |  |
Windows 95 + OSR2.5 | 400 |  | 1111 |
Windows 98 (Gold) | 410 |  | 1998 |
Windows 98 Second Edition | 410 |  | 2222 |
Windows Millennium Edition | 490 |  | 3000.1 |
Windows NT 4.0 (Gold) |  | 400 | 1381 |
Windows NT 4.0 + Service Pack 1 |  | 400 | 1381 | 1
Windows NT 4.0 + Service Pack 2 |  | 400 | 1381 | 2
Windows NT 4.0 + Service Pack 3 |  | 400 | 1381 | 3
Windows NT 4.0 + Service Pack 4 |  | 400 | 1381 | 4
Windows NT 4.0 + Service Pack 5 |  | 400 | 1381 | 5
Windows NT 4.0 + Service Pack 6 |  | 400 | 1381 | 6
Windows 2000 |  | 500 | 2195 |
"Whistler" |  | 501 | 2264 or greater |


Platform SDK Components for Windows Installer Developers

The Platform SDK components for the Microsoft® Windows® Installer Software Development Kit can be downloaded from the following MSDN web page.

Error! Bookmark not defined.

This includes the redistributable components, documentation, installer database validation tool, database table editor, database schema, development tools, VBScript tools, sample product, and code samples.


Released Versions of Windows Installer

[This is preliminary documentation and subject to change.]

The follow table lists the released versions of the Microsoft Windows Installer.

Released Version | Version | Description
Windows Installer 1.0 | 1.00.5104.0 | Released with Office 2000 and as a redistributable.
Windows Installer 1.1 | 1.10.1029.0 | Released with Windows 2000.
 | 1.10.1029.1 | Released as a redistributable.
Windows Installer 1.2 | 1.20.1410.0 | Released with Windows Millennium Edition.
 | 1.20.1827.1 | Released as a redistributable.

To determine the Windows Installer version, call MsiGetFileVersion with the szFilePath parameter set to the path to the file Msi.dll.

The four-field string in the above table is also equivalent to the Version Property (Installer Object).


Windows Installer Development Tools

[This is preliminary documentation and subject to change.]

The following tools are only available in the Platform SDK Components for Windows Installer Developers.

Utility | Description
Msidb.exe | Imports and exports database tables and streams, merges databases, and applies transforms.
Msimsp.exe | Patch creation tool. The recommended method for generating a patch package is to use a patch creation tool such as Msimsp.exe with Patchwiz.dll.
Patchwiz.dll | Generates a Windows Installer patch package from a patch creation properties file (.pcp file). The recommended method for generating a patch package is to use a patch creation tool such as Msimsp.exe with Patchwiz.dll.
Msiinfo.exe | Edits or displays summary information stream.
Msimerg.exe | Merges one database into another.
Msitran.exe | Generates a transform or applies a transform file to a database.
Orca.exe | Database editor. Creates and edits .msi files and merge modules.
Msival2.exe | Runs one or a suite of Internal Consistency Evaluators - ICEs.
Msispy.exe | Provides a component level view of the products and features installed on a system using either a Windows Installer package or the registry information.
Msizap.exe | Removes Windows Installer information for a product or all products installed on a machine.
Msitool.mak | Makefile that can be used to make tools and custom actions.
Msistuff.exe | Displays or configures the resources in the Setup.exe bootstrap executable.


Msidb.exe

[This is preliminary documentation and subject to change.]

Msidb.exe uses MsiDatabaseImport and MsiDatabaseExport to import and export database tables and streams.

If the mode, folder, database and table list are specified on the command line, Msidb.exe does not bring up any user interface and operates as a silent command-line utility suitable for build script.

Syntax

MsiDb {option}...{option}... {table}...{table}

Command Line Options

Msidb.exe uses the following case-insensitive command line options. A slash delimiter may also be used in place of a dash.

Option | Description
-i | Import text archive files from folder into database. Table names for import are file names 8 characters long with an ".idt" extension. Longer names are truncated to 8 characters if supplied by command for import. Standard wild card specifications may be used.
-e | Export selected tables from database into text archive files in folder. Table names for export are table names. Only the wildcard specification, "*", may be used. Tables may be exported from a read only database.
-c | Creates a new database file and imports tables. Overwrites an existing database file.
-f | Specifies the folder containing the text archive files for tables and streams. If the folder containing the text archive files is not specified, the utility prompts the user for the folder.
-d | Fully-qualified path to the database file.
-m | Fully-qualified path to the database that is to be merged in. This option is available only in silent command line mode. Multiple instances of this option may occur to a maximum of 10. If the database is not specified on the command-line, the utility prompts the user for the database.
-t | Fully-qualified path to the transform to be applied. This option is available only in silent command line mode. Multiple instances of this option may occur to a maximum of 10.
-j | Name of storage to remove from the database. This option is available only in silent command line mode. Multiple instances of this option may occur to a maximum of 10.
-k | Name of stream to remove from the database. This option available only in silent command line mode. Multiple instances of this option may occur to a maximum of 10.
-x | Name of stream to save to a disk file in the current directory. This option is available only in silent command line mode. Binary data streams are stored as separate files with the extension ".ibd". Binary filename used is primary key data for the row containing the stream.
-w | Name of storage to save to a disk file in the current directory. This option is available only in silent command line mode.
-a | Name of file to add to the database as a stream. This option is available only in silent command line mode. Multiple instances of this option may occur to a maximum of 10. Binary data streams are stored as separate files with the extension ".ibd". Binary filename used is primary key data for the row containing the stream.
-r | Name of storage to add to the database as a substorage. This option available only in silent command line mode. Multiple instances of this option may occur to a maximum of 10.
-s | Truncate table names to 8 chars on export to an .idt. The table name is truncated to 8 characters and the extension ".idt" is added.
-? | Displays the command line help dialog

Note When using long filenames with spaces, use quotes around them. For example, for a database that is in the 'My Documents' folder, specify it as "c:\my documents".

See Also

Windows Installer Development Tools


Msimsp.exe

[This is preliminary documentation and subject to change.]

The recommended method for generating a patch package is to use a patch creation tool such as Msimsp.exe and Patchwiz.dll. The tool Msimsp.exe is provided in the Platform SDK Components for Windows Installer Developers. The source code for Patchwiz.dll is also provided in the SDK so that you can customize and enhance the patch creation process.

The Msimsp.exe tool is a executable that calls PatchWiz.dll. The tool may be used to create a patch package by passing in the path to a patch creation properties file (.pcp file) and the path to the patch package being created. The tool can also be used to create a log file and to specify a temporary folder in which the transforms, cabinets and files used to create the patch package are saved. The command line syntax for Msimsp.exe is:

Msimsp.exe -s [path to .pcp file] -p [path to .msp file] {options}

The command line options are not case-sensitive and slash delimiters may be used instead of a dash. If no options are specified, Msimsp.exe displays the current values of the summary Information properties.

Option | Parameter | Description
-s | path to .pcp file | This is required and must be followed by the path to the patch creation properties file (.pcp extension). For more information about patch creation files see PatchWiz.dll.
-p | path to .msp file | This is required and followed by the path to patch package being created (.msp extension).
-f | path to temporary folder | Optional. Followed by path to temporary folder. The default location is %TEMP%\~pcw_tmp.tmp\.
-k |  | Optional. Fail if the temporary folder already exists.
-l | path to log file | Optional. Followed by the path to log file describing patch creation process and errors. See Return Values for UiCreatePatchPackage.
-d |  | Optional. Displays a dialog if the patch creation completes successfully.
-? |  | Displays command line help.

See Also

A Small Update Patching Example, Windows Installer Development Tools


Patchwiz.dll

[This is preliminary documentation and subject to change.]

The recommended method for generating a patch package is to use a patch creation tool such as Msimsp.exe and Patchwiz.dll. The tool Msimsp.exe is provided in the Platform SDK Components for Windows Installer Developers. The source code for Patchwiz.dll is also provided in the SDK so that you can customize and enhance the patch creation process.

The PatchWiz.dll has one API, UiCreatePatchPackage (Patchwiz.dll), that takes a patch creation properties file (.pcp file) and generates a Windows Installer patch package.

The .pcp file is a binary database file with the same format as a Windows Installer database (an .msi file) but with a different database schema. Therefore a .pcp file can be authored using the same tools as used for a Windows installer database. Authors may create a .pcp file by using a table editor such Orca to enter their information into the blank .pcp database provided with the SDK, template.pcp. An example of the procedure is discussed in the section A Small Update Patching Example.

The following database tables are required in every .pcp file.

  • Properties Table (Patchwiz.dll)
  • ImageFamilies Table (Patchwiz.dll)
  • UpgradedImages Table (Patchwiz.dll)
  • TargetImages Table (Patchwiz.dll)

The following are optional tables.

  • UpgradedFiles_OptionalData Table (Patchwiz.dll)
  • FamilyFileRanges Table (Patchwiz.dll)
  • TargetFiles_OptionalData Table (Patchwiz.dll)
  • ExternalFiles Table (Patchwiz.dll)
  • UpgradedFilesToIgnore Table (Patchwiz.dll)


UiCreatePatchPackage (Patchwiz.dll)

[This is preliminary documentation and subject to change.]

The UiCreatePatchPackage function is the one API of PatchWiz.dll. It takes a package creation file (.pcp file) and generates a Windows Installer patch package (.msp package). Calling Msimsp.exe is the recommended method for using PatchWiz.dll.

UINT UiCreatePatchPackage(
  LPCTSTR szPcpPath,              // path to .pcp file
  LPCTSTR szPatchPath,            // path to .msp file or NULL
  LPCTSTR szLogPath,              // path to log file or NULL
  HWND hwndStatus,                // handle to window or NULL
  LPCTSTR szTempFolder,           // temp file location or NULL
  Bool fRemoveTempFolderContents  // remove temp folder
);

Parameters

szPcpPath
Full path to the patch creation properties file (.pcp file) for this patch.
szPatchPath
Full path to the Windows Installer patch package (.msp file) that is to be created. This parameter may be NULL or an empty string but may not be omitted. If it is NULL or an empty string, the function uses the value of PatchOutputPath in the Properties Table (Patchwiz.dll).
szLogPath
Full path to a text log file that will be appended. This parameter may be NULL or an empty string but may not be omitted.
hwndStatus
Handle to a window that displays the status text. This parameter may be NULL or an empty string but may not be omitted.
szTempFolder
Location for temporary files. This parameter may be NULL or an empty string but may not be omitted. The default location is %TEMP%\~pcw_tmp.tmp\.
fRemoveTempFolderContents
If TRUE, remove the temporary folder and all of its contents if present. If FALSE, and folder is present, the function fails.

Return Values

See Return Values for UiCreatePatchPackage.

Remarks

For an example of authoring a .pcp file and using UiCreatePatchPackage to generate a Windows Installer patch package, see the section A Small Update Patching Example.


Return Values for UiCreatePatchPackage

[This is preliminary documentation and subject to change.]

UiCreatePatchPackage (Patchwiz.dll) may return the following values. The return value is ERROR_SUCCESS plus the values in this table.

Error Code | Description | Value | Decimal
ERROR_PCW_BASE | Base return value (0xC00E5101) | (0xC00E5101) | 3222163713
ERROR_PCW_PCP_DOESNT_EXIST | Patch creation properties file doesn't exist. | (ERROR_PCW_BASE + 0x00) | 3222163713
ERROR_PCW_PCP_BAD_FORMAT | Patch creation properties file format invalid. | (ERROR_PCW_BASE + 0x01) | 3222163714
ERROR_PCW_CANT_CREATE_TEMP_FOLDER | Cannot create temporary folder. | (ERROR_PCW_BASE + 0x02) | 3222163715
ERROR_PCW_MISSING_PATCH_PATH | Missing PatchOutputPath in Properties Table. | (ERROR_PCW_BASE + 0x03) | 3222163716
ERROR_PCW_CANT_OVERWRITE_PATCH | Unable to overwrite patch. | (ERROR_PCW_BASE + 0x04) | 3222163717
ERROR_PCW_CANT_CREATE_PATCH_FILE | Unable to create patch file. | (ERROR_PCW_BASE + 0x05) | 3222163718
ERROR_PCW_MISSING_PATCH_GUID | Missing PatchGUID in Properties Table. | (ERROR_PCW_BASE + 0x06) | 3222163719
ERROR_PCW_BAD_PATCH_GUID | Invalid PatchGUID in Properties Table. | (ERROR_PCW_BASE + 0x07) | 3222163720
ERROR_PCW_BAD_GUIDS_TO_REPLACE | Invalid ListOfPatchGUIDsToReplace in Properties Table. | (ERROR_PCW_BASE + 0x08) | 3222163721
ERROR_PCW_BAD_TARGET_PRODUCT_CODE_LIST | Invalid ListOfTargetProductCodes in Properties Table. | (ERROR_PCW_BASE + 0x09) | 3222163722
ERROR_PCW_NO_UPGRADED_IMAGES_TO_PATCH | No images to patch in the Upgraded field of UpgradedImages Table. | (ERROR_PCW_BASE + 0x0a) | 3222163723
 | not used | (ERROR_PCW_BASE + 0x0b) | 3222163724
ERROR_PCW_BAD_API_PATCHING_SYMBOL_FLAGS | Invalid ApiPatchingSymbolFlags in Properties Table. | (ERROR_PCW_BASE + 0x0c) | 3222163725
ERROR_PCW_OODS_COPYING_MSI | Out of disk space copying .msi file. | (ERROR_PCW_BASE + 0x0d) | 3222163726
ERROR_PCW_UPGRADED_IMAGE_NAME_TOO_LONG | Name too long in Upgraded of UpgradedImages Table. | (ERROR_PCW_BASE + 0x0e) | 3222163727
ERROR_PCW_BAD_UPGRADED_IMAGE_NAME | Invalid name in Upgraded of UpgradedImages Table. | (ERROR_PCW_BASE + 0x0f) | 3222163728
ERROR_PCW_DUP_UPGRADED_IMAGE_NAME | Duplicate names in Upgraded of UpgradedImages Table. | (ERROR_PCW_BASE + 0x10) | 3222163729
ERROR_PCW_UPGRADED_IMAGE_PATH_TOO_LONG | Path too long in MsiPath of UpgradedImages Table. | (ERROR_PCW_BASE + 0x11) | 3222163730
ERROR_PCW_UPGRADED_IMAGE_PATH_EMPTY | Empty path in MsiPath of UpgradedImages Table. | (ERROR_PCW_BASE + 0x12) | 3222163731
ERROR_PCW_UPGRADED_IMAGE_PATH_NOT_EXIST | Nonexisting path in MsiPath of UpgradedImages Table. | (ERROR_PCW_BASE + 0x13) | 3222163732
ERROR_PCW_UPGRADED_IMAGE_PATH_NOT_MSI | Path not to .msi file in MsiPath of UpgradedImages Table. | (ERROR_PCW_BASE + 0x14) | 3222163733
ERROR_PCW_UPGRADED_IMAGE_COMPRESSED | Compressed upgraded image referenced by Upgraded in UpgradedImages Table. Upgraded images must be fully uncompressed. | (ERROR_PCW_BASE + 0x15) | 3222163734
ERROR_PCW_TARGET_IMAGE_NAME_TOO_LONG | Name too long in Target of TargetImages Table. | (ERROR_PCW_BASE + 0x16) | 3222163735
ERROR_PCW_BAD_TARGET_IMAGE_NAME | Invalid name in Target of TargetImages Table. | (ERROR_PCW_BASE + 0x17) | 3222163736
ERROR_PCW_DUP_TARGET_IMAGE_NAME | Duplicate name in Target of TargetImages Table. | (ERROR_PCW_BASE + 0x18) | 3222163737
ERROR_PCW_TARGET_IMAGE_PATH_TOO_LONG | Path too long in MsiPath of TargetImages Table.. | (ERROR_PCW_BASE + 0x19) | 3222163738
ERROR_PCW_TARGET_IMAGE_PATH_EMPTY | Empty path in MsiPath of TargetImages Table. | (ERROR_PCW_BASE + 0x1a) | 3222163739
ERROR_PCW_TARGET_IMAGE_PATH_NOT_EXIST | Non-existing path in MsiPath of TargetImages Table. | (ERROR_PCW_BASE + 0x1b) | 3222163740
ERROR_PCW_TARGET_IMAGE_PATH_NOT_MSI | Path not to .msi file in MsiPath of TargetImages Table. | (ERROR_PCW_BASE + 0x1c) | 3222163741
ERROR_PCW_TARGET_IMAGE_COMPRESSED | Compressed target image referenced by Target of TargetImages Table. Target images must be fully uncompressed. | (ERROR_PCW_BASE + 0x1d) | 3222163742
ERROR_PCW_TARGET_BAD_PROD_VALIDATE | Invalid value in ProductValidateFlags of TargetImages Table. | (ERROR_PCW_BASE + 0x1e) | 3222163743
ERROR_PCW_TARGET_BAD_PROD_CODE_VAL | Invalid product code for target referenced in Target of TargetImages Table. | (ERROR_PCW_BASE + 0x1f) | 3222163744
ERROR_PCW_UPGRADED_MISSING_SRC_FILES | Missing source files in upgraded image referenced by Upgraded in UpgradedImages Table. | (ERROR_PCW_BASE + 0x20) | 3222163745
ERROR_PCW_TARGET_MISSING_SRC_FILES | Missing source files in target image referenced by Target in TargetImages Table. | (ERROR_PCW_BASE + 0x21) | 3222163746
ERROR_PCW_IMAGE_FAMILY_NAME_TOO_LONG | Name too long in Family of ImageFamilies Table (Patchwiz.dll). | (ERROR_PCW_BASE + 0x22) | 3222163747
ERROR_PCW_BAD_IMAGE_FAMILY_NAME | Invalid name in Family of ImageFamilies Table (Patchwiz.dll). | (ERROR_PCW_BASE + 0x23) | 3222163748
ERROR_PCW_DUP_IMAGE_FAMILY_NAME | Duplicate name in Family of ImageFamilies Table (Patchwiz.dll). | (ERROR_PCW_BASE + 0x24) | 3222163749
ERROR_PCW_BAD_IMAGE_FAMILY_SRC_PROP | Invalid MediaSrcPropName in ImageFamilies Table (Patchwiz.dll). | (ERROR_PCW_BASE + 0x25) | 3222163750
ERROR_PCW_UFILEDATA_LONG_FILE_TABLE_KEY | File table key too long in FTK of UpgradedFiles_OptionalData Table. | (ERROR_PCW_BASE + 0x26) | 3222163751
ERROR_PCW_UFILEDATA_BLANK_FILE_TABLE_KEY | Blank file table key in FTK of UpgradedFiles_OptionalData Table. | (ERROR_PCW_BASE + 0x27) | 3222163752
ERROR_PCW_UFILEDATA_MISSING_FILE_TABLE_KEY | Missing file table key in FTK of UpgradedFiles_OptionalData Table. | (ERROR_PCW_BASE + 0x28) | 3222163753
ERROR_PCW_EXTFILE_LONG_FILE_TABLE_KEY | File table key too long in FTK of ExternalFiles Table. | (ERROR_PCW_BASE + 0x29) | 3222163754
ERROR_PCW_EXTFILE_BLANK_FILE_TABLE_KEY | Blank file table key in FTK of ExternalFiles Table. | (ERROR_PCW_BASE + 0x2a) | 3222163755
ERROR_PCW_EXTFILE_BAD_FAMILY_FIELD | Invalid image family in Family of ExternalFiles Table. | (ERROR_PCW_BASE + 0x2b) | 3222163756
ERROR_PCW_EXTFILE_LONG_PATH_TO_FILE | Path too long in FilePath of ExternalFiles Table. | (ERROR_PCW_BASE + 0x2c) | 3222163757
ERROR_PCW_EXTFILE_BLANK_PATH_TO_FILE | Blank path in FilePath of ExternalFiles Table. | (ERROR_PCW_BASE + 0x2d) | 3222163758
ERROR_PCW_EXTFILE_MISSING_FILE | Missing path in FilePath of ExternalFiles Table. | (ERROR_PCW_BASE + 0x2e) | 3222163759
ERROR_PCW_FILERANGE_LONG_FILE_TABLE_KEY | File table key too long in FTK of FamilyFileRanges Table. | (ERROR_PCW_BASE + 0x2f) | 3222163760
ERROR_PCW_FILERANGE_BLANK_FILE_TABLE_KEY | Blank file table key in FTK of FamilyFileRanges Table. | (ERROR_PCW_BASE + 0x30) | 3222163761
ERROR_PCW_FILERANGE_MISSING_FILE_TABLE_KEY | Missing file table key in FTK of FamilyFileRanges Table. | (ERROR_PCW_BASE + 0x31) | 3222163762
ERROR_PCW_FILERANGE_LONG_PATH_TO_FILE | Path too long referenced by FamilyFileRanges Table. | (ERROR_PCW_BASE + 0x32) | 3222163763
ERROR_PCW_FILERANGE_MISSING_FILE | Missing file referenced by FamilyFileRanges Table. | (ERROR_PCW_BASE + 0x33) | 3222163764
ERROR_PCW_FILERANGE_INVALID_OFFSET | Invalid range offset in RetainOffsets in FamilyFileRanges Table. | (ERROR_PCW_BASE + 0x34) | 3222163765
ERROR_PCW_FILERANGE_INVALID_SIZE | Invalid range length in RetainLengths in FamilyFileRanges Table. | (ERROR_PCW_BASE + 0x35) | 3222163766
ERROR_PCW_FILERANGE_INVALID_RETAIN | Invalid target retained in FamilyFileRanges Table. | (ERROR_PCW_BASE + 0x36) | 3222163767
ERROR_PCW_BAD_MEDIA_SRC_PROP_NAME | Invalid MediaSrcPropName in ImageFamilies Table (Patchwiz.dll). | (ERROR_PCW_BASE + 0x37) | 3222163768
ERROR_PCW_BAD_MEDIA_DISK_ID | Invalid MediaDiskId in ImageFamilies Table (Patchwiz.dll). | (ERROR_PCW_BASE + 0x38) | 3222163769
ERROR_PCW_BAD_FILE_SEQUENCE_START | Invalid FileSequenceStart in ImageFamilies Table (Patchwiz.dll). | (ERROR_PCW_BASE + 0x39) | 3222163770
ERROR_PCW_CANT_COPY_FILE_TO_TEMP_FOLDER | Unable to copy a file to temporary folder. | (ERROR_PCW_BASE + 0x3a) | 3222163771
ERROR_PCW_CANT_CREATE_ONE_PATCH_FILE | Unable to create one patch file. | (ERROR_PCW_BASE + 0x3b) | 3222163772
ERROR_PCW_BAD_IMAGE_FAMILY_DISKID | Invalid MediaDiskId in ImageFamilies Table (Patchwiz.dll). | (ERROR_PCW_BASE + 0x3c) | 3222163773
ERROR_PCW_BAD_IMAGE_FAMILY_FILESEQSTART | Invalid FileSequenceStart in ImageFamilies Table (Patchwiz.dll). | (ERROR_PCW_BASE + 0x3d) | 3222163774
ERROR_PCW_BAD_UPGRADED_IMAGE_FAMILY | Invalid Family in UpgradedImages Table. | (ERROR_PCW_BASE + 0x3e) | 3222163775
ERROR_PCW_BAD_TARGET_IMAGE_UPGRADED | Invalid Upgraded in TargetImages Table. | (ERROR_PCW_BASE + 0x3f) | 3222163776
ERROR_PCW_DUP_TARGET_IMAGE_PACKCODE | Duplicate target image package codes. | (ERROR_PCW_BASE + 0x40) | 3222163777
ERROR_PCW_UFILEDATA_BAD_UPGRADED_FIELD | Invalid Upgraded in UpgradedFiles_OptionalData Table (Patchwiz.dll). | (ERROR_PCW_BASE + 0x41) | 3222163778
ERROR_PCW_MISMATCHED_PRODUCT_CODES | Mismatched product codes. | (ERROR_PCW_BASE + 0x42) | 3222163779
ERROR_PCW_MISMATCHED_PRODUCT_VERSIONS | Mismatched product versions. | (ERROR_PCW_BASE + 0x43) | 3222163780
ERROR_PCW_CANNOT_WRITE_DDF | Cannot write DDF. | (ERROR_PCW_BASE + 0x44) | 3222163781
ERROR_PCW_CANNOT_RUN_MAKECAB | Cannot make cabinet file. | (ERROR_PCW_BASE + 0x45) | 3222163782
ERROR_PCW_CANNOT_CREATE_STORAGE | Cannot create storage. | (ERROR_PCW_BASE + 0x46) | 3222163783
ERROR_PCW_CANNOT_CREATE_STREAM | Cannot create stream. | (ERROR_PCW_BASE + 0x47) | 3222163784
ERROR_PCW_CANNOT_WRITE_STREAM | Cannot write stream. | (ERROR_PCW_BASE + 0x48) | 3222163785
ERROR_PCW_CANNOT_READ_CABINET | Cannot read cabinet file. | (ERROR_PCW_BASE + 0x49) | 3222163786
ERROR_PCW_WRITE_SUMMARY_PROPERTIES | Error writing summary properties. | (ERROR_PCW_BASE + 0x4a) | 3222163787
ERROR_PCW_TFILEDATA_LONG_FILE_TABLE_KEY | File table key too long in FTK of TargetFiles_OptionalData Table. | (ERROR_PCW_BASE + 0x4b) | 3222163788
ERROR_PCW_TFILEDATA_BLANK_FILE_TABLE_KEY | Blank file table key in FTK of TargetFiles_OptionalData Table. | (ERROR_PCW_BASE + 0x4c) | 3222163789
ERROR_PCW_TFILEDATA_MISSING_FILE_TABLE_KEY | Missing file table key in FTK of TargetFiles_OptionalData Table. | (ERROR_PCW_BASE + 0x4d) | 3222163790
ERROR_PCW_TFILEDATA_BAD_TARGET_FIELD | Invalid target in Target of TargetFiles_OptionalData Table. | (ERROR_PCW_BASE + 0x4e) | 3222163791
ERROR_PCW_UPGRADED_IMAGE_PATCH_PATH_TOO_LONG | Path too long in PatchMsiPath of UpgradedImages Table. | (ERROR_PCW_BASE + 0x4f) | 3222163792
ERROR_PCW_UPGRADED_IMAGE_PATCH_PATH_NOT_EXIST | Nonexistent path in PatchMsiPath of UpgradedImages Table. | (ERROR_PCW_BASE + 0x50) | 3222163793
ERROR_PCW_UPGRADED_IMAGE_PATCH_PATH_NOT_MSI | Path in PatchMsiPath of UpgradedImages Table does not end in .msi file. | (ERROR_PCW_BASE + 0x51) | 3222163794
ERROR_PCW_DUP_UPGRADED_IMAGE_PACKCODE | Duplicate upgraded image package code. | (ERROR_PCW_BASE + 0x52) | 3222163795
ERROR_PCW_UFILEIGNORE_BAD_UPGRADED_FIELD | Invalid Upgraded in UpgradedFilesToIgnore Table (Patchwiz.dll). | (ERROR_PCW_BASE + 0x53) | 3222163796
ERROR_PCW_UFILEIGNORE_LONG_FILE_TABLE_KEY | File table key too long in FTK UpgradedFilesToIgnore Table (Patchwiz.dll). | (ERROR_PCW_BASE + 0x54) | 3222163797
ERROR_PCW_UFILEIGNORE_BLANK_FILE_TABLE_KEY | Blank file table key in FTK UpgradedFilesToIgnore Table (Patchwiz.dll). | (ERROR_PCW_BASE + 0x55) | 3222163798
ERROR_PCW_UFILEIGNORE_BAD_FILE_TABLE_KEY | Invalid file table key in FTK UpgradedFilesToIgnore Table (Patchwiz.dll). | (ERROR_PCW_BASE + 0x56) | 3222163799
ERROR_PCW_FAMILY_RANGE_NAME_TOO_LONG | Name too long in Family of FamilyFileRanges Table (Patchwiz.dll). | (ERROR_PCW_BASE + 0x57) | 3222163800
ERROR_PCW_BAD_FAMILY_RANGE_NAME | Invalid name in Family of FamilyFileRanges Table (Patchwiz.dll). | (ERROR_PCW_BASE + 0x58) | 3222163801
ERROR_PCW_FAMILY_RANGE_LONG_FILE_TABLE_KEY | File table key too long in FTK of FamilyFileRanges Table (Patchwiz.dll). | (ERROR_PCW_BASE + 0x59) | 3222163802
ERROR_PCW_FAMILY_RANGE_BLANK_FILE_TABLE_KEY | Blank file table key in FTK of FamilyFileRanges Table (Patchwiz.dll). | (ERROR_PCW_BASE + 0x5a) | 3222163803
ERROR_PCW_FAMILY_RANGE_LONG_RETAIN_OFFSETS | Range offset too long in RetainOffset of FamilyFileRanges Table (Patchwiz.dll). | (ERROR_PCW_BASE + 0x5b) | 3222163804
ERROR_PCW_FAMILY_RANGE_BLANK_RETAIN_OFFSETS | Blank range offset in RetainOffset of FamilyFileRanges Table (Patchwiz.dll). | (ERROR_PCW_BASE + 0x5c) | 3222163805
ERROR_PCW_FAMILY_RANGE_BAD_RETAIN_OFFSETS | Invalid range offset in RetainOffset of FamilyFileRanges Table (Patchwiz.dll). | (ERROR_PCW_BASE + 0x5d) | 3222163806
ERROR_PCW_FAMILY_RANGE_LONG_RETAIN_LENGTHS | Range length too long in RetainLength of FamilyFileRanges Table (Patchwiz.dll). | (ERROR_PCW_BASE + 0x5e) | 3222163807
ERROR_PCW_FAMILY_RANGE_BLANK_RETAIN_LENGTHS | Blank range length in RetainLength of FamilyFileRanges Table (Patchwiz.dll). | (ERROR_PCW_BASE + 0x5f) | 3222163808
ERROR_PCW_FAMILY_RANGE_BAD_RETAIN_LENGTHS | Blank range length in RetainLength of FamilyFileRanges Table (Patchwiz.dll). | (ERROR_PCW_BASE + 0x60) | 3222163809
ERROR_PCW_FAMILY_RANGE_COUNT_MISMATCH | Counts mismatch in RetainOffset and RetainLength of FamilyFileRanges Table (Patchwiz.dll). | (ERROR_PCW_BASE + 0x61) | 3222163810
ERROR_PCW_EXTFILE_LONG_IGNORE_OFFSETS | Range offset too long in IgnoreOffsets of ExternalFiles Table (Patchwiz.dll). | (ERROR_PCW_BASE + 0x62) | 3222163811
ERROR_PCW_EXTFILE_BAD_IGNORE_OFFSETS | Invalid range offset in IgnoreOffsets of ExternalFiles Table (Patchwiz.dll). | (ERROR_PCW_BASE + 0x63) | 3222163812
ERROR_PCW_EXTFILE_LONG_IGNORE_LENGTHS | Range length too long in IgnoreLengths of ExternalFiles Table (Patchwiz.dll). | (ERROR_PCW_BASE + 0x64) | 3222163813
ERROR_PCW_EXTFILE_BAD_IGNORE_LENGTHS | Invalid range length in IgnoreLengths of ExternalFiles Table (Patchwiz.dll). | (ERROR_PCW_BASE + 0x65) | 3222163814
ERROR_PCW_EXTFILE_IGNORE_COUNT_MISMATCH | Count of range lengths in IgnoreLengths mismatched in ExternalFiles Table (Patchwiz.dll). | (ERROR_PCW_BASE + 0x66) | 3222163815
ERROR_PCW_EXTFILE_LONG_RETAIN_OFFSETS | Range offset too long in RetainOffsets of ExternalFiles Table (Patchwiz.dll). | (ERROR_PCW_BASE + 0x67) | 3222163816
ERROR_PCW_EXTFILE_BAD_RETAIN_OFFSETS | Invalid range offsetin RetainOffsets of ExternalFiles Table (Patchwiz.dll). | (ERROR_PCW_BASE + 0x68) | 3222163817
ERROR_PCW_EXTFILE_RETAIN_COUNT_MISMATCH | Count of range offsets in RetainOffsets mismatched in ExternalFiles Table (Patchwiz.dll). | (ERROR_PCW_BASE + 0x69) | 3222163818
ERROR_PCW_TFILEDATA_LONG_IGNORE_OFFSETS | Range offset too long in IgnoreOffset of TargetFiles_OptionalData Table (Patchwiz.dll). | (ERROR_PCW_BASE + 0x6a) | 3222163819
ERROR_PCW_TFILEDATA_BAD_IGNORE_OFFSETS | Invalid range offset in IgnoreOffset of TargetFiles_OptionalData Table (Patchwiz.dll). | (ERROR_PCW_BASE + 0x6b) | 3222163820
ERROR_PCW_TFILEDATA_LONG_IGNORE_LENGTHS | Range length too long in IgnoreLength of TargetFiles_OptionalData Table (Patchwiz.dll). | (ERROR_PCW_BASE + 0x6c) | 3222163821
ERROR_PCW_TFILEDATA_BAD_IGNORE_LENGTHS | Invalid range length in IgnoreLength of TargetFiles_OptionalData Table (Patchwiz.dll). | (ERROR_PCW_BASE + 0x6d) | 3222163822
ERROR_PCW_TFILEDATA_IGNORE_COUNT_MISMATCH | Count error in ignored range offset or length TargetFiles_OptionalData Table (Patchwiz.dll). | (ERROR_PCW_BASE + 0x6e) | 3222163823
ERROR_PCW_TFILEDATA_LONG_RETAIN_OFFSETS | Range offset too long in RetainOffsets in TargetFiles_OptionalData Table (Patchwiz.dll). | (ERROR_PCW_BASE + 0x6f) | 3222163824
ERROR_PCW_TFILEDATA_BAD_RETAIN_OFFSETS | Invalid range offset in RetainOffsets in TargetFiles_OptionalData Table (Patchwiz.dll). | (ERROR_PCW_BASE + 0x70) | 3222163825
ERROR_PCW_TFILEDATA_RETAIN_COUNT_MISMATCH | Count error in RetainOffsets TargetFiles_OptionalData Table (Patchwiz.dll). | (ERROR_PCW_BASE + 0x71) | 3222163826
ERROR_PCW_CANT_GENERATE_TRANSFORM | Unable to generate transform. | (ERROR_PCW_BASE + 0x72) | 3222163827
ERROR_PCW_CANT_CREATE_SUMMARY_INFO | Unable to generate summary information. | (ERROR_PCW_BASE + 0x73) | 3222163828
ERROR_PCW_CANT_GENERATE_TRANSFORM_POUND | Unable to generate #-transform. | (ERROR_PCW_BASE + 0x74) | 3222163829
ERROR_PCW_CANT_CREATE_SUMMARY_INFO_POUND | Unable to create #-transform summary information. | (ERROR_PCW_BASE + 0x75) | 3222163830
ERROR_PCW_BAD_UPGRADED_IMAGE_PRODUCT_CODE | Invalid ProductCode in upgraded image. | (ERROR_PCW_BASE + 0x76) | 3222163831
ERROR_PCW_BAD_UPGRADED_IMAGE_PRODUCT_VERSION | Invalid ProductVersion in upgraded image. | (ERROR_PCW_BASE + 0x77) | 3222163832
ERROR_PCW_BAD_UPGRADED_IMAGE_UPGRADE_CODE | Invalid UpgradeCode in upgraded image. | (ERROR_PCW_BASE + 0x78) | 3222163833
ERROR_PCW_BAD_TARGET_IMAGE_PRODUCT_CODE | Invalid ProductCode in target. | (ERROR_PCW_BASE + 0x79) | 3222163834
ERROR_PCW_BAD_TARGET_IMAGE_PRODUCT_VERSION | Invalid ProductVersion in target. | (ERROR_PCW_BASE + 0x7a) | 3222163835
ERROR_PCW_BAD_TARGET_IMAGE_UPGRADE_CODE | Invalid UpgradeCode in target. | (ERROR_PCW_BASE + 0x7b) | 3222163836


Properties Table (Patchwiz.dll)

[This is preliminary documentation and subject to change.]

The Properties table contains global settings for the patch package. The Properties table is required in the patch creation database (.pcp file) and is used by UiCreatePatchPackage (Patchwiz.dll).

The Properties table has the following columns.

Column | Type | Key | Nullable
Name | text | Y | N
Value | text |  | Y

Columns

Name
The name of a patch creation property.
Value
Value of the patch creation property

Remarks

The following table lists the patch creation property strings that may be entered into the Properties Table of the .pcp file.

Property | Description
PatchGUID | A GUID identifier for this patch package (.msp file). Every patch package must have a unique PatchGUID value. Required.
PatchOutputPath | The full path, including filename, of the patch package file that is to be generated. If szPatchPath is passed by UiCreatePatchPackage the passed value is used. This property is required if szPatchPath is NULL or an empty string.
ListOfPatchGUIDsToReplace | A list of PatchGUID identifiers with no delimiter. If any of these patches are found to be installed on the user's computer and registered with Windows Installer, they are unregistered from the appropriate product and their patch transforms are removed from the list of transforms associated with the product. Note that the removal of a patch does not affect any of the files, only the registration of the patch. Optional.
ListOfTargetProductCodes | A list of product codes for products that may receive this patch. This is a semicolon delimited list of ProductCode property values. If the list begins with an asterisk, the list of product codes is generated from the .msi files of the targets listed in the TargetImages Table. If any product codes follow a leading asterisk, they are appended to the list that replaces the asterisk. Required.
PatchSourceList | A source used to locate the .msp file for the patch in the event that the locally cached copy is unavailable. This value is added to the source list of the patch when it is applied to a product. The source cannot be a URL with Windows Installer version 1.0. Optional.
AllowProductCodeMismatches | Set to '1' for True if the ProductCode property may differ between the upgraded images listed in the UpgradedImages Table and the target images listed in the TargetImages Table. The True setting requires Windows Installer version 1.1 on the target computer. Set to '0' or blank to mean False if the product codes must be the same.
AllowProductVersionMajorMismatches | Set to '1' to mean True if the first field (the major version field) of the ProductVersion property may differ between Upgraded images and Target images. The True setting requires Windows Installer version 1.1 on the target computer. Set to '0' or blank to mean False if the major versions must match.
ApiPatchingSymbolFlags | An 8-digit hex integer representing the combination of patch symbol usage flags to use when creating a binary file patch. Default is 0x00000000. See PATCHAPI.H for the complete list of possible PATCH_SYMBOL_* flags. See the glossary for more information on symbol files.
MsiFileToUseToCreatePatchTables | The full path to a template .msi file from which to export the Patch table and PatchPackage table. Optional.
DontRemoveTempFolderWhenFinished | Set to '1' to mean True if the temporary folder containing the transforms, the byte-level patches, and the entire new files are not being removed after creating the patch package. This is essentially the contents of the .msp file before being embedded into the patch package. This may be useful for debugging patches. Set to '0' or blank to mean False if the temporary folder is to be removed.
IncludeWholeFilesOnly | Set to '1' to mean True if files being changed are to be included in their entirety when creating the patch package instead of creating a binary file patch. The patch files will be bigger in size but the API runs faster. Set to '0' or blank to mean False if creating a binary file patch.
OptimizePatchSizeForLargeFiles | This property is set when the value exists and is not "0". When this property is set, patches for files greater than approximately 4 MB in size may be made smaller. This property requires Windows Installer version 1.2 or later. If this property is set, the Word Count Summary Property of the patch package is also set to "2." This means that this patch fails immediately when using a Windows Installer version earlier than version 1.2.


ImageFamilies Table (Patchwiz.dll)

[This is preliminary documentation and subject to change.]

An image family is a group of one or more upgraded images of a product that have been updated to the most recent version. Each upgraded image can belong to only one family. Upgraded images belonging to an image family share one or more files. Each image family has its own cabinet file in the .msp file containing the binary patches and new files needed to update the differences between target and upgraded files. The cabinet file does not replicate the binary patches and new files used by the shared files.

An ImageFamilies table containing at least one record is required in every patch creation database (.pcp file). This table is used by UiCreatePatchPackage.

The ImageFamilies table contains the patching information that is to be added to the Media table. A patch adds one entry to the Media table. Each record in the ImageFamilies tables refers to a group of related product images that have been updated to the most recent version of the product.

The ImageFamilies table has the following columns.

Column | Type | Key | Nullable
Family | text | Y | N
MediaSrcPropName | text |  | N
MediaDiskId | integer |  | N
FileSequenceStart | integer |  | N
DiskPrompt | text |  | Y
VolumeLabel | text |  | Y

Columns

Family
The value entered in this field is an identifier for a group of related product images that have been updated to the most recent version of the product. Limited to a total of 8 alphanumeric characters or underscores. The installer embeds a cabinet stream in the Windows Installer patch file (.msp file) for each family in the table. The cabinet contains the binary patches and new files required to update a target image into an upgraded image of the product. The installer prefixes the family name with PCW_CAB_ to generate the cabinet's stream name it enters into the Cabinet field of the new Media table entry.
MediaSrcPropName
The value entered into the Source field of the new Media table entry of the upgraded image.
MediaDiskId
The installer enters this value into the DiskId field of the new Media table record. The DiskID value must be greater than any current DiskID in the target package.
FileSequenceStart
This field is the sequence number for the starting file. This same file sequence number must not exist in two patches for the same product. To ensure this, the value in this field must be greater than all sequence numbers used in previous patches or in the original installation package. The greatest sequence number in a patch can be determined by adding the total number of entries in the patch cabinet file to the FileSequenceStart number for that patch. One way to determine this is to look at the .ddf file generated by PatchWiz.dll during the creation of the patch.
DiskPrompt
The installer enters this value into the DiskPrompt field of the new Media table record.
VolumeLabel
The installer enters this value into the VolumeLabel field of the new Media record.

Remarks

The patch adds the name of the cabinet in the .msp file to the Cabinet field of the new record added to the Media table. Because it is an embedded cabinet, the name is prefixed with a '#' character. The patch adds a property to the Source field of the new record in the Media table. No two patches may have the same source property.

The files that are shared within the image family must have the same file table key in each upgraded image of the family. Any file table keys shared among the upgraded images must represent the same file and must be identical in all the upgraded images. The file table key is the value entered in the File column of the File Table.


UpgradedImages Table (Patchwiz.dll)

[This is preliminary documentation and subject to change.]

The UpgradedImages table contains information about the upgraded images of the product. The upgraded image should be a fully uncompressed administrative image of the latest version of the product. A Windows Installer patch package updates a target image into an upgraded image. The UpgradedImages table is required in the patch creation database (.pcp file) and is used by UiCreatePatchPackage (Patchwiz.dll).

An UpgradedImages table containing at least one record is required in every patch creation database (.pcp file). This table is used by UiCreatePatchPackage.

The UpgradedImages table has the following columns.

Column | Type | Key | Nullable
Upgraded | text | Y | N
MsiPath | text |  | N
PatchMsiPath | text |  | Y
SymbolPaths | text |  | Y
Family | text |  | N

Columns

Upgraded
The Upgraded field is an arbitrary identifier to connect the target images with an upgraded image of the product.
MsiPath
This field specifies the full path, including the file name, to the location of the .msi file for the upgraded image. This is the location of the source files for the upgraded image.
PatchMsiPath
The optional patchMsiPath points to a modified copy of the upgraded installation database that contains additional authoring specific to the patch installation process. For example, additional dialogs or custom actions conditioned on the PATCH property.
SymbolPaths
A semicolon delimited list of folders that are to be searched for symbol files that may be used to optimize the generation of the binary patch. Note that the subdirectories of folders specified in this field are not searched. An optimized binary patch may be smaller. Visual C++ must be installed on the computer generating the patch and used to create the symbol files. This field is optional, and the installer creates a binary patch even if no symbol files are specified or if the symbol files become unavailable to Patchwiz.dll.
Family
Foreign key into the ImageFamilies Table. Each upgraded image must belong to only one family.

Remarks

Although each upgraded image can be grouped into a separate image family, grouping upgraded images that share files together may make the .msp smaller.


TargetImages Table (Patchwiz.dll)

[This is preliminary documentation and subject to change.]

The TargetImages table contains information about the target images of the product. A Windows Installer patch package updates a target image into an upgraded image.

A TargetImages table containing at least one record is required in every patch creation database (.pcp file). This table is used by UiCreatePatchPackage.

The TargetImages table has the following columns.

Column | Type | Key | Nullable
Target | text | Y | N
MsiPath | text |  | N
SymbolPaths | text |  | Y
Upgraded | text |  | N
Order | integer |  | N
ProductValidateFlags | text |  | Y
IgnoreMissingSrcFiles | integer |  | N

Columns

Target
Identifier for a target image. The patch package updates the target image specified in this column to the upgraded image specified in the Upgraded column. There are one or more target images for each upgraded image. The target image must be an fully uncompressed administrative image of the product because UiCreatePatchPackage does not generate binary patches for files in cabinets. The value in this field is used with the value in the Upgraded field to generate the names of the transforms that the installer adds to the patch package.
MsiPath
This field specifies the full path, including the file name, to the location of the .msi file for the target image. This is the location of the source files for the target image.
SymbolPaths
A semicolon delimited list of folders that are to be searched for symbol files that may be used to optimize the generation of the binary patch. Note that the subdirectories of folders specified in this field are not searched. An optimized binary patch may be smaller. Visual C++ must be installed on the computer generating the patch and used to create the symbol files. This field is optional, and the installer creates a binary patch even if no symbol files are specified or if the symbol files become unavailable to Patchwiz.dll.
Upgraded
Foreign key to the Upgraded column of the UpgradedImages Table. UiCreatePatchPackage ignores any upgraded image that is not referenced by at least one record of the TargetImages table.
Order
Relative order of the target image. Because multiple targets can be patched to an upgraded image, the Order field provides a means to sequence the transforms in the patch transforms list. Commonly the order is from oldest to newest image.
ProductValidateFlags
The ProductValidateFlags field is used to specify product checking to avoid applying irrelevant transforms. The value entered in this field must be an 8-digit hex integer and one of the valid values for the iValidation parameter of MsiCreateTransformSummaryInfo. The default value is 0x00000922 which equals MSITRANSFORM_VALIDATE_UPDATEVERSION + MSITRANSFORM_VALIDATE_NEWEQUALBASEVERSION + MSITRANSFORM_VALIDATE_UPGRADECODE + MSITRANSFORM_VALIDATE_PRODUCT.
IgnoreMissingSrcFiles
If this field is set to a non-zero value, files missing from the target image are ignored by the installer and left unchanged during patching. This enables patches to be made without requiring the entire administrative image; only the changed files of the product and the .msi file are required. This may reduce the time required to generate the patch.


UpgradedFiles_OptionalData Table (Patchwiz.dll)

[This is preliminary documentation and subject to change.]

The UpgradedFile_OptionalData table contains information about specific files in an upgraded image. This table is optional in the patch creation database (.pcp file) and is used by UiCreatePatchPackage (Patchwiz.dll).

The UpgradedFiles_OptionalData table has the following columns.

Column | Type | Key | Nullable
Upgraded | text | Y | N
FTK | text | Y | N
SymbolPaths | text |  | Y
AllowIgnoreOnPatchError | integer |  | Y
IncludeWholeFile | integer |  | Y

Columns

Upgraded
Foreign key to the Upgraded column of the UpgradedImages Table (Patchwiz.dll).
FTK
File table key. Foreign key into File table of the .msi file of the upgraded image. If two or more upgraded images within a family have the same FTK value, the value must refer to the same file. Files shared by multiple upgrade images should have the same FTK to minimize cabinet file size.
SymbolPaths
The value in this field is added to the semicolon delimited list of folders in the SymbolPaths column of the UpgradedImages Table (Patchwiz.dll) when the patch is generated, and can be used to add symbol files for a specific file.
AllowIgnoreOnPatchError
Set to 1 to indicate that the patch is non-vital. Set to 0 to indicate that the patch is vital. If the Windows Installer encounters a problem when applying this patch to the file specified in the FTK column, the value in this field determines whether the error message box includes an 'Ignore' button to enable the user to continue the patching process.
IncludeWholeFile
Set to a non-zero value if the entire file specified in the FTK column should be installed rather than creating a binary patch.


FamilyFileRanges Table (Patchwiz.dll)

[This is preliminary documentation and subject to change.]

The FamilyFileRanges table contains information about particular files of an upgraded image that have ranges that should never be overwritten. This table is optional in the patch creation database (.pcp file) and is used by UiCreatePatchPackage (Patchwiz.dll).

The FamilyFileRanges table has the following columns.

Column | Type | Key | Nullable
Family | text | Y | N
FTK | text | Y | N
RetainOffsets | text |  | N
RetainLengths | text |  | N

Columns

Family
Foreign key to the Family column of the ImageFamilies Table (Patchwiz.dll).
FTK
Foreign key into the File tables of all the upgraded images in the image family.
RetainOffsets
The offset of the ranges that cannot be overwritten. The value in this field is a list of the range offset numbers for ranges that are not to be overwritten in the target files. The order and number of the ranges in the list must match the items in the RetainLengths column.
RetainLengths
The size of the ranges that cannot be overwritten. The value in this field is a list of range length numbers for ranges to retain in target files. The order and number of the ranges in the list must match the items in the RetainOffsets column.

Remarks

The offsets and lengths entered in RetainOffsets and RetainLengths must not specify overlapping ranges.


TargetFiles_OptionalData Table (Patchwiz.dll)

[This is preliminary documentation and subject to change.]

The TargetFiles_OptionalData table contains information about specific files in a target image. This table is optional in the patch creation database (.pcp file) and is used by UiCreatePatchPackage (Patchwiz.dll).

The TargetFiles_OptionalData table has the following columns.

Column | Type | Key | Nullable
Target | text | Y | N
FTK | text | Y | N
SymbolPaths | text |  | Y
IgnoreOffsets | text |  | Y
IgnoreLengths | text |  | Y
RetainOffsets | text |  | Y

Columns

Target
Foreign key to the Target column of the TargetImages Table (Patchwiz.dll).
FTK
Foreign key into the File table of target image.
SymbolPaths
The value in this field is added to the semicolon delimited list of folders in the SymbolPaths column of the TargetImages Table (Patchwiz.dll) when the patch is generated, and can be used to add symbol files for a specific file.
IgnoreOffsets
The value in this field is a comma delimited list of range offset numbers for the ranges to be ignored in the Target file. The order and number of the ranges in the list must match the items in the IgnoreLengths column. This column is optional.
IgnoreLengths
The value in this field is a comma delimited list of range lengths for the ranges to be ignored in the Target file. The order and number of the ranges in the list must match the items in the IgnoreOffsets column. This column is optional.
RetainOffsets
The value in this field is a comma delimited list of range offset numbers for the ranges to be retained in the Target file. The order and number of the ranges in the list must match the items in the RetainOffsets column of the corresponding record in the FamilyFileRanges Table (Patchwiz.dll).


ExternalFiles Table (Patchwiz.dll)

[This is preliminary documentation and subject to change.]

The ExternalFiles table contains information about specific files that are not part of a regular target image. These files may exist in products that have been updated by another product, upgrade, or patch. This table is optional in the patch creation database (.pcp file) and is used by UiCreatePatchPackage.

The ExternalFiles table has the following columns.

Column | Type | Key | Nullable
Family | text | Y | N
FTK | text | Y | N
FilePath | text | Y | N
SymbolPaths | text |  | Y
Order | integer |  | Y
IgnoreOffsets | text |  | Y
IgnoreLengths | text |  | Y
RetainOffsets | text |  | N

Columns

Family
Foreign key to the Family column of the ImageFamilies Table (Patchwiz.dll).
FTK
Foreign key into File table of the .msi file of the upgraded image.
FilePath
Full path of the external file including the filename. FilePath field is used to locate the file specified in the FTK column.
SymbolPaths
Full path searched for symbol files of the file specified in the FTK column.
Order
If two or more versions are specified for the same external file, the table may contain multiple records with matching values in the FTK and Family fields. In this case, the Order field may specify the order of external files to use when creating the patch. The order is from the oldest to the most recent version.
IgnoreOffsets
The value in this field is a comma delimited list of range offset numbers for the ranges to be ignored in the external file. The order and number of the ranges in the list must match the items in the IgnoreLengths column. This column is optional.
IgnoreLengths
The value in this field is a comma delimited list of range lengths for the ranges to be ignored in the External file. The order and number of the ranges in the list must match the items in the IgnoreOffsets column. This column is optional.
RetainOffsets
The value in this field is a comma delimited list of range offset numbers for the ranges to be retained in the External file. The order and number of the ranges in the list must match the items in the RetainOffsets column of the corresponding record in the FamilyFileRanges Table (Patchwiz.dll).


UpgradedFilesToIgnore Table (Patchwiz.dll)

[This is preliminary documentation and subject to change.]

The UpgradedFilesToIgnore table prevents the updating of specific files that are in fact changed in the upgraded image relative to the target images. It may be useful to do this in certain cases. For example, a patch package that is intended only for use with non-administrative installations does not need to include patching files that are only part of administrative images. Excluding the files used only in administrative images can reduce the size of the patch package in this case; however, administrators should be informed on how to update these files separately. This table is optional in the patch creation database (.pcp file) and is used by UiCreatePatchPackage (Patchwiz.dll).

The UpgradedFilesToIgnore table has the following columns.

Column | Type | Key | Nullable
Upgraded | text | Y | N
FTK | text | Y | N

Columns

Upgraded
Foreign key to the Upgraded column of the UpgradedImages Table (Patchwiz.dll). The patch creation tool excludes updating the file specified in the FTK column of the UpgradedFilesToIgnore table when upgrading a target to the image specified in the Upgraded field. Enter a value of "*" in the Upgraded field to exclude updating the file for all upgraded images.
FTK
Foreign key into the File table of the upgraded image. A value of the form "<prefix>*" will match all file table keys in the File table that begin with that prefix. No text can follow the asterisk.


Msiinfo.exe

[This is preliminary documentation and subject to change.]

Msiinfo.exe is a command line utility that uses Database Functions and Installer Functions to edit or display the summary information stream of a database.

Syntax

MsiInfo {database} [[/B] /D] {option} {data}
  • The database cannot be a read-only database.
  • If no data follows an option, the corresponding property is removed.
  • A maximum of 20 options may be specified on the command line. The same properties can be specified multiple times.
  • If the data contains a space, enclose the data with quote marks. For example, such as /T "MY TITLE".

Command Line Options

Msiinfo.exe uses the following case-insensitive command line options. A slash delimiter may also be used in place of a dash. For more information see Summary Information Stream Property Set.

Option | Description | Property ID | PID
none | If no options are specified, the utility displays the current values of the Summary Information properties. |  |
-b | Display information about every string in the string pool. The -b option is only valid if -d is also used and -b must come before the -d option. |  |
-d | Display information about the string pool. Validates the string pool and provides information about the codepage of the database. Note that the codepage of the database is different than the codepage of the Summary Information stream (PID_CODEPAGE). This option also checks every string for characters that are invalid in the codepage of the database. |  |
-i | Not applicable. Reserved. | PID_DICTIONARY | 0
-c | Sets the Codepage Summary Property. | PID_CODEPAGE | 1
-t | Sets the Title Summary Property. | PID_TITLE | 2
-j | Sets the Subject Summary Property. | ID PID_SUBJECT | 3
-a | Sets the Author Summary Property. | PID_AUTHOR | 4
-k | Sets the Keywords Summary Property. | PID_KEYWORDS | 5
-o | Sets the Comments Summary Property. | PID_COMMENTS | 6
-p | Sets the Template Summary Property. | PID_TEMPLATE | 7
-l | Sets the Last Saved By Summary Property. | PID_LASTAUTHOR | 8
-v | Sets the Revision Number Summary Property. | PID_REVNUMBER | 9
-e | Not applicable. Reserved | PID_EDITTIME | 10
-s | Sets the Last Printed Summary Property. To specify the year, month, day, hour, minute, and second, use the format "yyyy/mm/dd hh:mm:ss." For example, "1997/06/20 03:25:59". | PID_LASTPRINTED | 11
-r | Sets the Create Time/Date Summary Property. To specify the year, month, day, hour, minute, and second, use the format "yyyy/mm/dd hh:mm:ss." For example, "1997/06/20 03:25:59". | PID_CREATE_DTM | 12
-q | Sets the Last Saved Time/Date Summary Property. To specify the year, month, day, hour, minute, and second, use the format "yyyy/mm/dd hh:mm:ss." For example, "1997/06/20 03:25:59". | PID_LASTSAVE_DTM | 13
-g | Sets the Page Count Summary Property. | PID_PAGECOUNT | 14
-w | Sets the Word Count Summary Property. | PID_WORDCOUNT | 15
-h | Sets the Character Count Summary Property. | PID_CHARCOUNT | 16
 | Not applicable. Reserved. | PID_THUMBNAIL | 17
-n | Sets the Creating Application Summary Property. | PID_APPNAME | 18
-u | Sets the Security Summary Property. | PID_SECURITY | 19

See Also

Windows Installer Development Tools


Msimerg.exe

[This is preliminary documentation and subject to change.]

Msimerg.exe is a command line utility that uses MsiDatabaseMerge to merge a reference database into a base database.

Syntax

Msimerg {base database} {reference database}
  • If there is a merge conflict between the two databases, the conflict information is placed in the _MergeErrors table.

Command Line Options

None.

See Also

Windows Installer Development Tools


Msitran.exe

[This is preliminary documentation and subject to change.]

Msitran.exe uses MsiDatabaseGenerateTransform, MsiCreateTransformSummaryInfo, and MsiDatabaseApplyTransform to generate or apply a transform file.

Syntax

Use the following syntax to generate a transform.

msitran -g {base db} {ref db} {transform file name} [{error conditions / validation conditions}]

Use the following syntax to apply a transform

msitran -a {transform} {database} [{error conditions}]

Command Line Options

Msitran.exe uses the following case-insensitive command line options. A slash delimiter may also be used in place of a dash.

Option | Description
-g | Transform generation.
-a | Transform application.

The following errors may be suppressed when applying a transform. To suppress an error, include the appropriate character in the {error conditions} argument. Conditions specified with -g are placed in the summary information of the transform, but are not used when applying a transform with -a. For information see MsiDatabaseApplyTransform.

Option | Suppressed Error
a | Add existing row.
b | Delete non-existing row.
c | Add existing table.
d | Delete non-existing table.
e | Modify existing row.
f | Change codepage.

The following validation conditions may be used to indicate when a transform may be applied to a package. These conditions may be specified with -g, but not -a.

Option | Validation Condition
g | Check upgrade code.
l | Check language.
p | Check platform.
r | Check product.
s | Check major version only.
t | Check major and minor versions only.
u | Check major, minor, and upgrade versions.
v | Applied database version < Base database version.
w | Applied database version <= Base database version.
x | Applied database version = Base database version.
y | Applied database version >= Base database version.
z | Applied database version > Base database version.

See Also

Windows Installer Development Tools, Transforms, A Customization Transform Example


Orca.exe

[This is preliminary documentation and subject to change.]

Orca.exe is a database table editor for creating and editing Windows installer packages and merge modules. The tool provides a graphical interface for validation, highlighting the particular entries where validation errors or warnings occur.

Syntax

orca [<options>] [<source file>]

Command Line Options

Orca.exe uses the following case-insensitive command line options. A slash delimiter may also be used in place of a dash.

Option | Description
-q | Quiet mode
-s | <database> Schema database ["orca.dat" - default]
-? | Help dialog

Orca.exe uses the following case-insensitive command line options with merge modules. A slash delimiter may also be used in place of a dash. When performing a merge the -f, -m and <sourcefile> are all required.

Option | Description
-c | Commit merge to database if no errors.
-m | <module> Merge Module to merge into database
-f | Feature[:Feature2] Feature(s) to connect to Merge Module
-r | <directory id> Directory entry for module root redirection
-x | <directory> Extract files to source image under directory
-g | <language> Language used to open module
-l | <log file> File to use as log, append if already exists

See Also

Windows Installer Development Tools


Msival2.exe

[This is preliminary documentation and subject to change.]

Msival2.exe is a command line utility that can run a suite of Internal Consistency Evaluators - ICEs.

Syntax

Msival2 {database} {CUB file} [-f] [-l {logfile}] [-i {ICE Id}[:{ICE Id}...]]

Command Line Options

Msival2.exe uses the following case-insensitive command line options. A slash delimiter may also be used in place of a dash.

Option | Description
-f | Filter out all informational messages from the displayed results. All other types of messages are displayed.
-i | Run only the ICEs listed on the command line in the order specified. Each ICE custom action should be listed as it appears in the CustomAction table of the CUB file. If this option is omitted, the tool runs the default set of ICEs specified by the author of the CUB file.
-l | Write results to the specified file. The file must not already exist. If the file exists, it is not overwritten.

See Also

Windows Installer Development Tools, Internal Consistency Evaluators - ICEs


Msispy.exe

[This is preliminary documentation and subject to change.]

Msispy.exe provides a component level view of the products and features installed on a system using either a Windows Installer package or the registry information. MSISPY displays the status of each product and feature and allows you to partially or completely reinstall missing or damaged items. You can also reconfigure any product or feature, select the install level, and specify whether to install it locally or run it from a network server.

Help files are installed when you install Msispy.

See Also

Windows Installer Development Tools


Msizap.exe

[This is preliminary documentation and subject to change.]

Msizap.exe is a command line utility that removes all Windows Installer information for a product or all products installed on a computer. Products installed by the Windows Installer may fail to function after using MsiZap.

Syntax

msizap T[A!] {product code}
msizap T[A!] <msi package>
msizap *[A!] ALLPRODUCTS
msizap PSA?!

Command Line Options

Msizap.exe uses the following case-insensitive command line options.

Option | Description
* | Remove all Windows Installer folders and registry keys, adjust shared DLL counts, and stop Windows Installer service.
t | Remove all information for the specified product code. When using this option, enclose the Product Code in curly braces. This option may be used with either the full path to the .msi file or with the product code.
p | Remove the In-Progress key.
s | Remove Rollback Information.
a | Only change ACLs to Admin Full Control for any specified removal.
? | Verbose help.
! | Force a 'yes' response to any prompt.

See Also

Windows Installer Development Tools


Msitool.mak

[This is preliminary documentation and subject to change.]

Msitool.mak is a makefile that you can use to build tools and custom actions. It may be used with VC4.x or VC5. For information see the header file of that file. It requires a set of values to be defined before including this file. Typically we put those at the start of the CPP, ifdef'd to be skipped by the C compiler. Likewise resources are added to the end of the CPP file. See samples for details.

VCBIN may be defined to the directory where the VC tools are found, else the makefile uses MSVCDIR and MSDEVDIR, and if those aren't defined, it does not specify a location, assuming the tools to be on the PATH. A problem with the environment variables in VC5 is that if both are NOT on you path, the linker can't find MSDIS100.DLL. If you copy that from MSDEVDIR to MSVCDIR, it works OK. The other thing that you can do is to copy MSDIS100.DLL and RC.EXE and RCDLL.DLL to MSVCDIR, and set VCBIN to that.

See Also

Windows Installer Development Tools


Msistuff.exe

[This is preliminary documentation and subject to change.]

Msistuff.exe is a command line utility that can be used to display or configure the resources in the Setup.exe bootstrap executable.

Syntax

msistuff setup.exe option {value}

If no data is specified following an option, that resource is removed.

Command Line Options

Msistuff.exe uses the following case-insensitive command line options. A slash delimiter may also be used in place of a dash. If an option is listed multiple times, only the last occurrence one is used.

Option | Resource ID | Description
no options specified |  | Display configurable resources in Setup.exe.
-u | ISETUPPROPNAME_BASEURL | Set BaseURL, the base URL location of Setup.exe. If no value is present, the location of Setup.exe defaults to removable media. Only URL based installs are subject to a check with WinVerifyTrust. The trailing slash on the URL is optional. This option may be omitted.
-d | ISETUPPROPNAME_DATABASE | Set Msi, the name of the .msi file. This is a relative path to the .msi file in relation to the location of the Setup.exe program. This option is required.
-n | ISETUPPROPNAME_PRODUCTNAME | Set Product Name, the name of the product. This provides the name used in the banner text for the downloaded user interface. This option may be omitted. If omitted, the default is "the product".
-v | ISETUPPROPNAME_MINIMUM_MSI | Set Minimum Msi Version, the minimum version of the Windows Installer required on the machine. If the minimum version of the Windows Installer is not present on the machine, the appropriate Instmsi.exe is installed to upgrade the Windows Installer. The value of this property has the same format as the PID_PAGECOUNT value. See Page Count Summary Property. The value must be at least 150, the value for the Windows Installer version 1.5. This option is required.
-i | ISETUPPROPNAME_INSTLOCATION | Set InstMsi URL Location, the base URL location of the Windows Installer upgrade executables. If this value is missing, the location of the upgrade executables defaults to the location of Setup.exe. This option may be omitted.
-a | ISETUPPROPNAME_INSTMSIA | Set InstMsiA, the name of the ANSI version of the Windows Installer upgrade executable. This is a relative path to the ANSI version of Instmsi.exe relative to the location specified by ISETUPPROPNAME_INSTLOCATION. This option is required.
-w | ISETUPPROPNAME_INSTMSIW | Set InstMsiW, the name of the Unicode version of the Windows Installer upgrade executable. This is a relative path to the Unicode version of Instmsi.exe relative to the location specified by ISETUPPROPNAME_INSTLOCATION. This option is required.
-p | ISETUPPROPNAME_PROPERTIES | Set the PROPERTY=VALUE strings. These are the PROPERTY=VALUE pairs to include on the command line. This option may be omitted. This option cannot be listed multiple times. This option must be listed last on the command line. All of the command line following -p is considered as a part of the {value}.
-c |  | Predownloaded cabinets
-l |  | Specifies path to log file and the flags that indicate which information to log. These are the same as the logging mode flags used for msiexec /L i - Status messages w - Non-fatal warnings e - All error messages a - Start up of actions r - Action-specific records u - User requests c - Initial UI parameters m - Out-of-memory or fatal exit information o - Out-of-disk-space messages p - Terminal properties v - Verbose output + - Append to existing file ! - Flush each line to the log "*" - Wildcard, log all information except for the v option. To include the v option, specify "/l*v".

See Also

Windows Installer Development Tools, Internet Download Bootstrapping, A URL Based Windows Installer Installation Example


Windows Installer and Logo Requirements

The Certified for Microsoft® Windows® Logo identifies products that have been verified through independent testing to comply with the Application Specification for Windows 2000. This specification was developed by Microsoft in cooperation with customers and other developers to provide a road map for building reliable and manageable applications. Software vendors who comply with the specification qualify for the Certified for Microsoft Windows logo and then license the logo for use on their product packaging, advertising, collateral, and other marketing materials.

For more information about the Application Specification for Windows 2000 and how to earn the Certified for Windows logo for your application, see http://msdn.microsoft.com/certification/default.asp. Download the Application Specification for Windows 2000 at http://msdn.microsoft.com/certification/appspec.asp.

If you are authoring an installation package for your application, you may take advantage of the capabilities of the Microsoft Windows Installer to help satisfy several of the requirements for certification. The following table provides links to information in the Windows Installer documentation pertinent for some of the certification requirements. Note that the not every requirement for certification discussed in the Application Specification for Windows 2000 is dependent upon the Windows Installer.

The following table refers to the chapter and requirement number described in the Application Specification for Windows 2000. For example, the row marked 2.3 refers to certification requirement 3 in chapter 2.

Requirement for Certification See the following sections
1.1

Application should perform primary functionality and maintain stability.

 If you provide an installation package, your application can use the Windows Installer service available on all 32-bit Windows platforms. Using the Installer can improve the functionality and stability of your application. See Resiliency

Overview of Windows Installer

Roadmap to Windows Installer Documentation.
1.3

Application should support Long File Names and UNC paths

 The installer supports installing to and from both UNC and drive network and always uses the long file names provided in your package except if the SHORTFILENAMES property is set or if the target volume does not support long file names. See Filename, File Table, Directory Table, SHORTFILENAMES Property.
1.5

The application should not read from or write to Win.ini, System.ini, Autoexec.bat or Config.sys on any Windows operating system based on Windows NT technology.

 Your installation program should add entries to the registry not to the Win.ini, System.ini, Autoexec.bat or Config.sys on any Windows operating system based on Windows NT technology. The Windows Installer supports informational keys in the registry. When your application uses the installer, these registry keys become available as installer properties. You can author the package for your application such that it is easy to check and set the values of these keys.

If your application uses information that you do not want to put in the registry, create a private initialization file and place it in the directory with the application's executable files. You can easily manage the installation of a private .ini file, as well as add or remove information from existing .ini files, by using the Windows Installer to install your application. See Modifying the Registry, Registry Tables Group, Registry Table, RemoveRegistry Table, WriteRegistryValues Action, RemoveRegistryValues Action, Uninstall Registry Key, Properties, File Table, Directory Table, Using the Directory Table, IniFile Table, RemoveIniFile Table, IniLocator Table, WriteIniValues Action , RemoveIniValues Action, RemoveIniFile Table.
1.7

The application should perform Windows version checking correctly.

 When you prepare an installation package for your application, you must include information about the product's operating system version requirements. On initialization, the installer automatically sets certain properties to the version of the current operating system. Your setup program can use these installer properties to provide easy version checking. See Properties, Version9X Property, VersionDatabase Property, VersionNT Property, WindowsBuild Property, ProductCode Property, ProductName Property, ProductVersion Property, Summary Information Stream, Revision Number Summary Property.
2.1

The application should install using a Windows Installer package that passes validation testing.

 You can check that your installation package passes validation testing by using a specific set of validation rules known as Internal Consistency Evaluators - ICEs. These ICEs are contained in the file Logo.cub. To qualify for certification, an installation package must not produce any errors when validated using these rules. Warnings are acceptable, but generally should be corrected.

The Windows Installer version 1.1 SDK includes the Logo.cub, Darice.cub, and Mergemod.cub files. The ICEs in the Logo.cub file are included in the Darice.cub file. If your package passes validation using Darice.cub, it will pass with Logo.cub. For more information, see Package Validation.

2.2

The installation package used to install the application should follow the rules for creating components.

 An installer component is a part of an application that is always installed or removed as one piece. There is a set of rules to help you decide how best to divide your application into components. If the components in your installation package are correctly defined, the installer can install and remove them safely. See Organizing Applications into Components, Components and Features, Changing the Component Code, What happens if the component rules are broken?, Working with Features and Components, Component Table.
2.3

The application's installation package should identify shared components.

 If you provide an installation package that correctly organizes your application into components, and set msidbComponentAttributesSharedDllRefCount in the Component Table, the Windows Installer can track shared components using the reference count in the shared DLL registry of the component's key file. If you do not use the installer, then your application must keep track of its use of shared DLLs by incrementing a usage counter for the DLL in the SharedDLLs registry key.

For more information, see Directory Table, Using the Directory Table, Component Table. For the discussion of the SharedDllRefCount bit, see Component Table, Organizing Applications into Components.
2.4

The application should install to the Program Files folder by default.

 On initialization, the installer sets a property to the full path of the Program Files folder. When you prepare the installation package you can specify that the installer install your application to this folder by default. If you also include a UI in your package, the installer can provide users with an option to select another installation location. For more information, see Directory Table, Using the Directory Table, TARGETDIR Property, MsiSetTargetPath, Properties, ProgramFilesFolder Property.
2.5

The application should support Add/Remove Program Files properly.

 You can supply all the information that is needed by Add/Remove Programs in the Control Panel by setting the values of certain installer properties in your application's Windows Installer package. Setting these properties automatically writes the corresponding values into the registry. See Properties, Required Properties, ProductName Property, ARPINSTALLLOCATION Property, Manufacturer Property, ProductVersion Property.
2.6

The application should ensure that the Windows Installer package supports advertising.

 Support advertising by organizing your application for advertising and by including all the information needed for advertisement in the application's Windows Installer package. For more information, see Advertisement, Installation-On-Demand, Publishing Products, Features, and Components, Platform Support of Advertisement, Components and Features, Suggested AdvtExecuteSequence, Suggested AdvtUISequence, Advertise Property, Advertise Action, PublishProduct Action, Feature Table, Shortcut Table, Class Table, Extension Table, Icon Table, MIME Table, ProgId Table, TypeLib Table, Verb Table, MsiConfigureFeature, MsiConfigureProduct.
2.7

The application's installation package should ensure correct uninstall support.

 If you use the installer to install your application, you do not need to create a separate uninstaller. You can author an installation package that enables the installer to install, uninstall, and repair your application. See Overview of Windows Installer, Organizing Applications into Components, Standard Actions, About Standard Actions, Using Standard Actions, Standard Actions Reference, Installing an Application, MsiInstallProduct, INSTALL Action.
3.1

On Windows 2000 do not attempt to replace files that are protected by Windows File Protection.

 The Windows Installer adheres to Windows File Protection (WFP) when installing essential system files on Windows 2000. The Windows Installer never attempts to install or replace a protected file. If a protected system file is modified by an unattended installation of an application, WFP restores the file to the verified file version. For more information, see Windows File Protection on Windows 2000.
3.2

Authors writing new redistributable components must use side-by-side sharing techniques so their components can be installed into the application directory.

Authors of Windows Installer packages can specify that the installer copy the shared files (commonly shared DLLs) of an application into the application's folder rather than to a shared location. This private set of files (DLLs) are then used only by the application. See Isolated Components.
3.3

For Windows 2000 and Windows 98 Second Edition, any side-by-side DLLs that your application depends on must be installed into your application directory:

 Authors of Windows Installer packages can specify that the installer copy the shared files (commonly shared DLLs) of an application into the application's folder rather than to a shared location. This private set of files (DLLs) are then used only by the application. See Isolated Components or Installation of Isolated Components.
4.3

The application should degrade gracefully if access is denied.

 The objective of this requirement is to ensure that if the user is denied access to resources, the application fails in a manner that maintains a secure environment.

The Windows Installer handles privileges only during installation. The application must handle privileges at run time. The installer can set certain properties on initialization to the user's privilege level or to a level specified by System Policy. You can then author your Windows Installer package such that the installer checks the user's access privileges before installation begins.

You can author the installation package so that the installer determines whether there is sufficient disk space. If you author a user interface (UI) for the application's package, it can display options to users that run out of disk space.

If the installation is unsuccessful, the installer can switch into its rollback mode and automatically restore the original state of the computer.

For more information, see Overview of Windows Installer, Resiliency, Source Resiliency, Privileged Property, AdminUser Property, System Policy, InstallValidate Action, File Costing, DiskCost Dialog, OutOfDiskSpace Property, OutOfNoRbDiskSpace Property, AllocateRegistrySpace Action, VolumeCostList Control, Rollback, Installation Mechanism, PROMPTROLLBACKCOST Property, DISABLEROLLBACK Property, EnableRollback ControlEvent.
4.5

The application should adhere to system-level Group Policy settings.

 Windows Installer can follow policies pertaining to installation. For more information, see System Policy.
7.1

Applications should continue to function after upgrade to Microsoft Windows 2000 Professional without reinstall

The installer has a component attribute that can facilitate preparation of your application for migration to Windows 2000. For more information, see Using Transitive Components.


Windows Installer Error Messages

Microsoft® Windows® Installer errors have an error code of 1000 or greater. The error codes 1000 to 1999 are ship errors and must be authored into the Error table. The error codes above 2000 are internal errors and do not have authored strings, but these can occur if the installation package has been incorrectly authored. For a list of reserved error codes see Error table.

Developers of installation packages can also test the internal consistency of their packages by using Internal Consistency Evaluators. For more information, see Internal Consistency Evaluators - ICEs.

Code | Message | Remarks
1101 | Could not open file stream: [2]. System error: [3] |
1301 | Cannot create the file '[2]'. A directory with this name already exists. |
1302 | Please insert the disk: [2] |
1303 | The Installer has insufficient privileges to access this directory: [2]. |
1304 | Error Writing to File: [2] |
1305 | Error Reading from File: [2]; System error code: [3] |
1306 | The file '[2]' is in use. If you can, please close the application that is using the file, then click Retry. |
1307 | There is not enough disk space remaining to install this file: [2]. If you can, free up some disk space, and click Retry, or click Cancel to exit. |
1308 | Source file not found: [2] |
1309 | Error attempting to open the source file: [3]. System error code: [2] |
1310 | Error attempting to create the destination file: [3]. System error code: [2] |
1311 | Could not locate source file cabinet: [2]. |
1312 | Cannot create the directory '[2]'. A file with this name already exists. Please rename or remove the file and click retry, or click Cancel to exit. |
1313 | The volume [2] is currently unavailable. Please select another. |
1314 | The specified path '[2]' is unavailable. |
1315 | Unable to write to the specified folder: [2]. |
1316 | A network error occurred while attempting to read from the file: [2] |
1317 | An error occurred while attempting to create the directory: [2] |
1318 | A network error occurred while attempting to create the directory: [2] |
1319 | A network error occurred while attempting to open the source file cabinet: [2]. |
1320 | The specified path is too long: '[2]' |
1321 | The Installer has insufficient privileges to modify this file: [2]. |
1322 | A portion of the folder path '[2]' is invalid. It is either empty or exceeds the length allowed by the system. |
1323 | The folder path '[2]' contains words that are not valid in folder paths. |
1324 | The folder path '[2]' contains an invalid character. |
1325 | '[2]' is not a valid short file name. |
1326 | Error getting file security: [3] GetLastError: [2] |
1327 | Invalid Drive: [2] |
1328 | Error applying patch to file [2]. It has probably been updated by other means, and can no longer be modified by this patch. For more information contact your patch vendor. System Error: [3] | Only available with Windows Installer version 1.1.
1329 | A file that is required cannot be installed because the cabinet file [2] is not digitally signed. This may indicate that the cabinet file is corrupt. | Only available with Windows Installer version 1.5 and later.
1330 | A file that is required cannot be installed because the cabinet file [2] has an invalid digital signature. This may indicate that the cabinet file is corrupt.{ Error [3] was returned by WinVerifyTrust.} | Only available with Windows Installer version 1.5 and later.
1331 | Failed to correctly copy [2] file: CRC error. | Only available with Windows Installer version 1.5 and later.
1332 | Failed to correctly move [2] file: CRC error. | Only available with Windows Installer version 1.5 and later.
1333 | Failed to correctly patch [2] file: CRC error. | Only available with Windows Installer version 1.5 and later.
1401 | Could not create key: [2]. System error [3]. |
1402 | Could not open key: [2]. System error [3]. |
1403 | Could not delete value [2] from key [3]. System error [4]. |
1404 | Could not delete key [2]. System error [3]. |
1405 | Could not read value [2] from key [3]. System error [4]. |
1406 | Could not write value [2] to key [3]. System error [4]. |
1407 | Could not get value names for key [2]. System error [3]. |
1408 | Could not get sub key names for key [2]. System error [3]. |
1409 | Could not read security information for key [2]. System error [3]. |
1410 | Could not increase the available registry space. [2] KB of free registry space is required for the installation of this application. |
1500 | Another installation is in progress. You must complete that installation before continuing this one. |
1501 | Error accessing secured data. Please make sure the Windows Installer is configured properly and try the install again. |
1502 | User '[2]' has previously initiated an install for product '[3]'. That user will need to run that install again before they can use that product. Your current install will now continue. |
1503 | User '[2]' has previously initiated an install for product '[3]'. That user will need to run that install again before they can use that product. |
1601 | Out of disk space -- Volume: '[2]'; required space: [3] KB; available space: [4] KB |
1602 | Are you sure you want to cancel? |
1603 | The file [2][3] is being held in use by the following process: Name: [4], Id: [5], Window Title: '[6]'. |
1604 | The product '[2]' is already installed, and has prevented the installation of this product. |
1605 | Out of disk space -- Volume: '[2]'; required space: [3] KB; available space: [4] KB. If rollback is disabled, enough space is available. Click 'Cancel' to quit, 'Retry' to check available disk space again, or 'Ignore' to continue without rollback. |
1606 | Could not access location [2]. |
1607 | The following applications should be closed before continuing the install: |
1608 | Could not find any previously installed compliant products on the machine for installing this product |
1701 | [2] is not a valid entry for a product ID. |
1702 | Configuring [2] cannot be completed until you restart your system. To restart now and resume configuration click Yes, or click No to stop this configuration. |
1703 | For the configuration changes made to [2] to take effect you must restart your system. To restart now click Yes, or click No if you plan to manually restart at a later time. |
1704 | An install for [2] is currently suspended. You must undo the changes made by that install to continue. Do you want to undo those changes? |
1705 | A previous install for this product is in progress. You must undo the changes made by that install to continue. Do you want to undo those changes? |
1706 | No valid source could be found for product [2]. |
1707 | Installation operation completed successfully. |
1708 | Installation operation failed. |
1709 | Product: [2] -- [3] |
1710 | You may either restore your computer to its previous state or continue the install later. Would you like to restore? |
1711 | An error occurred while writing installation information to disk. Check to make sure enough disk space is available, and click Retry, or Cancel to end the install. |
1712 | One or more of the files required to restore your computer to its previous state could not be found. Restoration will not be possible. |
1713 | [2] cannot install one of its required products. Contact your technical support group. System Error: [3]. | Only available with Windows Installer version 1.1.
1714 | The older version of [2] cannot be removed. Contact your technical support group. System Error [3]. | Only available with Windows Installer version 1.1.
1715 | Installed [2]. | Only available with Windows Installer version 1.2.
1716 | Configured [2]. | Only available with Windows Installer version 1.2.
1717 | Removed [2]. | Only available with Windows Installer version 1.2.
1718 | File [2] was rejected by digital signature policy. | Only available with Windows Installer version 1.5 and later.
1719 | The Windows Installer Service could not be accessed. Contact your support personnel to verify that it is properly registered and enabled. | Only available with Windows Installer version 1.5 and later.
1720 | There is a problem with this Windows Installer package. A script required for this install to complete could not be run. Contact your support personnel or package vendor. Custom action [2] script error [3], [4]: [5] Line [6], Column [7], [8] | Only available in Windows Installer version 1.5 and later.
1721 | There is a problem with this Windows Installer package. A program required for this install to complete could not be run. Contact your support personnel or package vendor. Action: [2], location: [3], command: [4] | Only available in Windows Installer version 1.5 and later.
1722 | There is a problem with this Windows Installer package. A program run as part of the setup did not finish as expected. Contact your support personnel or package vendor. Action [2], location: [3], command: [4] | Only available in Windows Installer version 1.5 and later.
1723 | There is a problem with this Windows Installer package. A DLL required for this install to complete could not be run. Contact your support personnel or package vendor. Action [2], entry: [3], library: [4] | Only available in Windows Installer version 1.5 and later.
1801 | The path [2] is not valid |
1802 | Out of memory |
1803 | There is no disk in drive [2]. Please, insert one and hit Retry, or hit Cancel to go back to the previously selected volume. |
1804 | There is no disk in drive [2]. Please, insert one and hit Retry, or hit Cancel to return to the browse dialog and select a different volume. |
1805 | The path [2] does not exist |
1806 | You have insufficient privileges to read this folder. |
1807 | A valid destination folder for the install could not be determined. |
1901 | Error attempting to read from the source install database: [2] |
1902 | Scheduling reboot operation: Renaming file [2] to [3]. Must reboot to complete operation. |
1903 | Scheduling reboot operation: Deleting file [2]. Must reboot to complete operation. |
1904 | Module [2] failed to register. HRESULT [3]. |
1905 | Module [2] failed to unregister. HRESULT [3]. |
1906 | Failed to cache package [2]. Error: [3] |
1907 | Could not register font [2]. Verify that you that you have sufficient permissions to install fonts, and that the system supports this font. |
1908 | Could not unregister font [2]. Verify that you that you have sufficient permissions to remove fonts. |
1909 | Could not create Shortcut [2]. Verify that the destination folder exists and that you can access it. |
1910 | Could not remove Shortcut [2]. Verify that the shortcut file exists and that you can access it. |
1911 | Could not register type library for file [2]. Contact your support personnel. |
1912 | Could not unregister type library for file [2]. Contact your support personnel. |
1913 | Could not update the ini file [2][3]. Verify that the file exists and that you can access it. |
1914 | Could not schedule file [2] to replace file [3] on reboot. Verify that you have write permissions to file [3]. |
1915 | Error removing ODBC driver manager, ODBC error [2]: [3]. Contact your support personnel. |
1916 | Error installing ODBC driver manager, ODBC error [2]: [3]. Contact your support personnel. |
1917 | Error removing ODBC driver: [4], ODBC error [2]: [3]. Verify that you have sufficient privileges to remove ODBC drivers. |
1918 | Error installing ODBC driver: [4], ODBC error [2]: [3]. Verify that the file [4] exists and that you can access it. |
1919 | Error configuring ODBC data source: [4], ODBC error [2]: [3]. Verify that the file [4] exists and that you can access it. |
1920 | Service '[2]' ([3]) failed to start. Verify that you have sufficient privileges to start system services. |
1921 | Service '[2]' ([3]) could not be stopped. Verify that you have sufficient privileges to stop system services. |
1922 | Service '[2]' ([3]) could not be deleted. Verify that you have sufficient privileges to remove system services. |
1923 | Service '[2]' ([3]) could not be installed. Verify that you have sufficient privileges to install system services. |
1924 | Could not update environment variable '[2]'. Verify that you have sufficient privileges to modify environment variables. |
1925 | You do not have sufficient privileges to complete this installation for all users of the machine. Log on as administrator and then retry this installation. |
1926 | Could not set file security for file '[3]'. Error: [2]. Verify that you have sufficient privileges to modify the security permissions for this file. |
1927 | The installation requires COM+ Services to be installed. | Only available with Windows Installer version 1.1.
1928 | The installation failed to install the COM+ Application. | Only available with Windows Installer version 1.1.
1929 | The installation failed to remove the COM+ Application. | Only available with Windows Installer version 1.1.
1930 | The description for service '[2]' ([3]) could not be changed. | Only available with Windows Installer version 1.1.
1931 | The Windows Installer service cannot update the system file [2] because the file is protected by Windows. You may need to update your operating system for this program to work correctly. Package version: [3], OS Protected version: [4] | Only available with Windows Installer version 1.1.
1932 | The Windows Installer service cannot update the protected Windows file [2]. Package version: [3], OS Protected version: [4], SFP Error: [5] | Only available with Windows Installer version 1.1.
2101 | Shortcuts not supported by the OS |
2102 | Invalid .INI action: [2] |
2103 | Could not resolve path for shell folder [2]. |
2104 | Writing .INI file: [3]: System error: [2] |
2105 | Shortcut Creation [3] Failed. System error: [2] |
2106 | Shortcut Deletion [3] Failed. System error: [2] |
2107 | Error [3] registering type library [2]. |
2108 | Error [3] unregistering type library [2]. |
2109 | Section missing for INI action. |
2110 | Key missing for INI action. |
2111 | Detection of running apps failed, could not get perf. data. Reg operation returned : [2]. |
2112 | Detection of running apps failed, could not get perf. index.Reg operation returned : [2]. |
2113 | Detection of running apps failed. |
2200 | Database: [2]. Database object creation failed, mode = [3] |
2201 | Database: [2]. Initialization failed, out of memory |
2202 | Database: [2]. Data access failed, out of memory |
2203 | Database: [2]. Cannot open database file. System error [3] |
2204 | Database: [2]. Table already exists: [3] |
2205 | Database: [2]. Table does not exist: [3] |
2206 | Database: [2]. Table could not be dropped: [3] |
2207 | Database: [2]. Intent violation |
2208 | Database: [2]. Insufficient parameters for Execute |
2209 | Database: [2]. Cursor in invalid state |
2210 | Database: [2]. Invalid update data type in column [3] |
2211 | Database: [2]. Could not create database table [3] |
2212 | Database: [2]. Database not in writable state |
2213 | Database: [2]. Error saving database tables |
2214 | Database: [2]. Error writing export file: [3] |
2215 | Database: [2]. Cannot open import file: [3] |
2216 | Database: [2]. Import file format error: [3], Line [4] |
2217 | Database: [2]. Wrong state to CreateOutputDatabase [3]. |
2218 | Database: [2]. Table name not supplied. |
2219 | Database: [2]. Invalid Installer database format |
2220 | Database: [2]. Invalid row/field data |
2221 | Database: [2]. Codepage conflict in import file: [3]. |
2222 | Database: [2]. Transform or merge codepage [3] differs from database codepage [4]. |
2223 | Database: [2]. Databases are the same. No transform generated. |
2224 | Database: [2]. GenerateTransform: Database corrupt. Table: [3] |
2225 | Database: [2]. Transform: Cannot transform a temporary table. Table: [3] |
2226 | Database: [2]. Transform failed. |
2227 | Database: [2]. Invalid identifier '[3]' in SQL query: [4] |
2228 | Database: [2]. Unknown table '[3]' in SQL query: [4] |
2229 | Database: [2]. Could not load table '[3]' in SQL query: [4] |
2230 | Database: [2]. Repeated table '[3]' in SQL query: [4] |
2231 | Database: [2]. Missing ')' in SQL query: [3] |
2232 | Database: [2]. Unexpected token '[3]' in SQL query: [4] |
2233 | Database: [2]. No columns in SELECT clause in SQL query: [3] |
2234 | Database: [2]. No columns in ORDER BY clause in SQL query: [3] |
2235 | Database: [2]. Column '[3]' not present or ambiguous in SQL query: [4] |
2236 | Database: [2]. Invalid operator '[3]' in SQL query: [4] |
2237 | Database: [2]. Invalid or missing query string: [3] |
2238 | Database: [2]. Missing FROM clause in SQL query: [3] |
2239 | Database: [2]. Insufficent values in INSERT SQL stmt |
2240 | Database: [2]. Missing update columns in UPDATE SQL stmt |
2241 | Database: [2]. Missing insert columns in INSERT SQL stmt |
2242 | Database: [2]. Column '[3]' repeated |
2243 | Database: [2]. No primary columns defined for table creation |
2244 | Database: [2]. Invalid type specifier '[3]' in SQL query [4]. |
2245 | IStorage::Stat failed with error [3] |
2246 | Database: [2]. Invalid Installer transform format. |
2247 | Database: [2] Transform stream read/write failure. |
2248 | Database: [2] GenerateTransform/Merge: Column type in base table doesn't match reference table. Table: [3] Col #: [4] |
2249 | Database: [2] GenerateTransform: More columns in base table than in reference table. Table: [3] |
2250 | Database: [2] Transform: Cannot add existing row. Table: [3] |
2251 | Database: [2] Transform: Cannot delete row that doesn't exist. Table: [3] |
2252 | Database: [2] Transform: Cannot add existing table. Table: [3] |
2253 | Database: [2] Transform: Cannot delete table that doesn't exist. Table: [3] |
2254 | Database: [2] Transform: Cannot update row that doesn't exist. Table: [3] |
2255 | Database: [2] Transform: Column with this name already exists. Table: [3] Col: [4] |
2256 | Database: [2] GenerateTransform/Merge: Number of primary keys in base table doesn't match reference table. Table: [3] |
2257 | Database: [2]. Intent to modify read only table: [3] |
2258 | Database: [2]. Type mismatch in parameter: [3] |
2259 | Database: [2] Table(s) Update failed |
2260 | Storage CopyTo failed. System error: [3] |
2261 | Could not remove stream [2]. System error: [3] |
2262 | Stream does not exist: [2]. System error: [3] |
2263 | Could not open stream [2]. System error: [3] |
2264 | Could not remove stream [2]. System error: [3] |
2265 | Could not commit storage. System error: [3] |
2266 | Could not rollback storage. System error: [3] |
2267 | Could not delete storage [2]. System error: [3] |
2268 | Database: [2]. Merge: There were merge conflicts reported in [3] tables |
2269 | Database: [2]. Merge: The column count differed in the '[3]' table of the two databases |
2270 | Database: [2]. GenerateTransform/Merge: Column name in base table doesn't match reference table. Table: [3] Col #: [4] |
2271 | SummaryInformation write for transform failed |
2272 | Database: [2]. MergeDatabase will not write any changes because the database is open read-only. |
2273 | Database: [2]. MergeDatabase: A reference to the base database was passed as the reference database. |
2274 | Database: [2]. MergeDatabase: Unable to write errors to Error table. Could be due to a non-nullable column in a predefined Error table. |
2275 | Database: [2]. Specified Modify [3] operation invalid for table joins. |
2276 | Database: [2]. Codepage [3] not supported by the system. |
2277 | Database: [2]. Failed to save table [3]. |
2278 | Database: [2]. Exceeded number of expressions limit of 32 in WHERE clause of SQL query: [3]. |
2279 | Database: [2] Transform: Too many columns in base table [3] |
2280 | Database: [2]. Could not create column [3] for table [4] |
2281 | Could not rename stream [2]. System error: [3] |
2282 | Stream name invalid [2]. |
2302 | Patch notify: [2] bytes patched to far. |
2303 | Error getting volume info. GetLastError: [2] |
2304 | Error getting disk free space. GetLastError: [2]. Volume: [3] |
2305 | Error waiting for patch thread. GetLastError: [2]. |
2306 | Could not create thread for patch application. GetLastError: [2]. |
2307 | Source file key name is null. |
2308 | Destination File Name is Null |
2309 | Attempting to patch file [2] when patch already in progress. |
2310 | Attempting to continue patch when no patch is in progress. |
2315 | Missing Path Separator: [2] |
2318 | File does not exist: [2] |
2319 | Error setting file attribute: [3] GetLastError: [2] |
2320 | File not writable: [2] |
2321 | Error creating file: [2] |
2322 | User cancelled |
2323 | Invalid File Attribute |
2324 | Could not open file: [3] GetLastError: [2] |
2325 | Could not get file time for file: [3] GetLastError: [2] |
2326 | Error in FileToDosDateTime. |
2327 | Could not remove directory: [3] GetLastError: [2] |
2328 | Error getting file version info for file: [2] |
2329 | Error deleting file: [3]. GetLastError: [2] |
2330 | Error getting file attributes: [3]. GetLastError: [2] |
2331 | Error loading library [2] or finding entry point [3] |
2332 | Error getting file attributes. GetLastError: [2] |
2333 | Error setting file attributes. GetLastError: [2] |
2334 | Error converting file time to local time for file: [3]. GetLastError: [2] |
2335 | Path: [2] is not a parent of [3] |
2336 | Error creating temp file on path: [3]. GetLastError: [2] |
2337 | Could not close file: [3] GetLastError: [2] |
2338 | Could not update resource for file: [3] GetLastError: [2] |
2339 | Could not set file time for file: [3] GetLastError: [2] |
2340 | Could not update resource for file: [3], Missing Resource |
2341 | Could not update resource for file: [3], Resource too large |
2342 | Could not update resource for file: [3] GetLastError: [2] |
2343 | Specified path is empty. |
2344 | Could not find required file IMAGEHLP.DLL to validate file:[2] |
2345 | [2]: File does not contain a valid checksum value. |
2347 | User Ignore |
2348 | Error attempting to read from cabinet stream. |
2349 | Copy Resumed With Different Info |
2350 | FDI Server Error |
2351 | File key '[2]' not found in cabinet '[3]'. The installation cannot continue. |
2352 | Couldn't initialize cabinet file server. The required file 'Cabinet.dll' may be missing. |
2353 | Not a cabinet |
2354 | Cannot handle cabinet |
2355 | Corrupt cabinet |
2356 | Couldn't locate cabinet in stream: [2]. |
2357 | Cannot set attributes |
2358 | Error determining whether file is in-use: [3]. GetLastError: [2] |
2359 | Unable to create the target file - file may be in use. |
2360 | progress tick. |
2361 | Need next cabinet. |
2362 | Folder not found: [2] |
2363 | Could not enumerate subfolders for folder: [2] |
2364 | Bad enumeration constant in CreateCopier call. |
2365 | Could not BindImage exe file [2] |
2366 | User Failure |
2367 | User Abort. |
2368 | Failed to get network resource information. Error [2], network path [3]. Extended error: network provider [5], error code [4], error description [6]. |
2371 | Could not apply patch to file [2]. GetLastError: [3] |
2372 | Patch file [2] is corrupt or of an invalid format. Attempting to patch file [3]. GetLastError: [4] |
2373 | File [2] is not a valid patch file. |
2374 | File [2] is not a valid destination file for patch file [3]. |
2375 | Unknown patching error: [2]. |
2376 | Cabinet not found. |
2379 | Error opening file for read: [3] GetLastError: [2] |
2380 | Error opening file for write: [3] GetLastError: [2] |
2381 | Directory does not exist: [2] |
2382 | Drive not ready: [2] |
2501 | Could not create rollback script enumerator |
2502 | Called InstallFinalize when no install in progress. |
2503 | Called RunScript when not marked in progress. |
2601 | Invalid value for property [2]: '[3]' |
2602 | The [2] table entry '[3]' has no associated entry in the Media table. |
2603 | Duplicate Table Name [2] |
2604 | [2] property undefined. |
2605 | Could not find server [2] in [3] or [4]. |
2606 | Value of property [2] is not a valid full path: '[3]'. |
2607 | Media table not found or empty (required for installation of files). |
2608 | Could not create security descriptor for object. Error: '[2]'. |
2609 | Attempt to migrate product settings before initialization. |
2611 | The file [2] is marked as compressed, but the associated media entry does not specify a cabinet. |
2612 | Stream not found in '[2]' column. Primary key: '[3]'. |
2613 | RemoveExistingProducts action sequenced incorrectly. | Only available with Windows Installer version 1.1.
2614 | Could not access IStorage object from installation package. | Only available with Windows Installer version 1.1.
2615 | Skipped unregistration of Module [2] due to source resolution failure. | Only available with Windows Installer version 1.1.
2616 | Companion file [2] parent missing. | Only available with Windows Installer version 1.1.
2617 | Shared component [2] not found in Component table. | Only available with Windows Installer version 1.1.
2618 | Isolated application component [2] not found in Component table. | Only available with Windows Installer version 1.1.
2619 | Isolated components [2], [3] not part of same feature. | Only available with Windows Installer version 1.1.
2620 | Key file of isolated application component [2] not in File table. | Only available with Windows Installer version 1.1.
2701 | The Component Table exceeds the acceptable tree depth of [2] levels. |
2702 | A Feature Table record ([2]) references a non-existent parent in the Attributes field. |
2703 | Property name for root source path not defined: [2] |
2704 | Root directory property undefined: [2] |
2705 | Invalid table: [2]; Could not be linked as tree. |
2706 | Source paths not created. No path exists for entry [2] in Directory Table |
2707 | Target paths not created. No path exists for entry [2] in Directory Table |
2708 | No entries found in the file table. |
2709 | The specified Component name ('[2]') not found in Component Table. |
2710 | The requested 'Select' state is illegal for this Component. |
2711 | The specified Feature name ('[2]') not found in Feature Table. |
2712 | Invalid return from modeless dialog: [3], in action [2]. |
2713 | Null value in a non-nullable column ('[2]' in '[3]' column of the '[4]' table. |
2714 | Invalid value for default folder name: [2]. |
2715 | The specified File key ('[2]') not found in the File Table. |
2716 | Couldn't create a random subcomponent name for component '[2]'. |
2717 | Bad action condition or error calling custom action '[2]'. |
2718 | Missing package name for product code '[2]'. |
2719 | Neither UNC nor drive letter path found in source '[2]'. |
2720 | Error opening sourcelist key. Error: '[2]' |
2721 | Custom action [2] not found in Binary table stream |
2722 | Custom action [2] not found in File table |
2723 | Custom action [2] specifies unsupported type |
2724 | The volume label '[2]' on the media you're running from doesn't match the label '[3]' given in the Media table. This is allowed only if you have only 1 entry in your Media table. |
2725 | Invalid database tables |
2726 | Action not found: [2] |
2727 | The directory entry '[2]' does not exist in the Directory table |
2728 | Table definition error: [2] |
2729 | Install engine not initialized. |
2730 | Bad value in database. Table: '[2]'; Primary key: '[3]'; Column: '[4]' |
2731 | Selection Manager not initialized. |
2732 | Directory Manager not initialized. |
2733 | Bad foreign key ('[2]') in '[3]' column of the '[4]' table. |
2734 | Invalid Reinstall mode character. |
2735 | Custom action terminated prematurely: [2] |
2736 | Generation of custom action temp file failed: [2] |
2737 | Could not access custom action [2], entry [3], library [4] | Only available in Windows Installer versions 1.0, 1.1, and 1.2.
2738 | Could not access VBScript runtime for custom action [2] |
2739 | Could not access JavaScript runtime for custom action [2] |
2740 | Custom action [2] script error [3], [4]: [5] Line [6], Column [7], [8] | Only available in Windows Installer versions 1.0, 1.1, and 1.2.
2741 | Configuration information for product [2] is corrupt. Invalid info: [2] |
2742 | Marshaling to Server failed: [2] |
2743 | Could not execute custom action [2], location: [3], command: [4] | Only available in Windows Installer versions 1.0, 1.1, and 1.2.
2744 | EXE failed called by custom action [2], location: [3], command: [4] | Only available in Windows Installer versions 1.0, 1.1, and 1.2.
2745 | Transform [2] invalid for package [3]. Expected language [4], found language [5]. |
2746 | Transform [2] invalid for package [3]. Expected product [4], found product [5]. |
2747 | Transform [2] invalid for package [3]. Expected product version < [4], found product version [5]. |
2748 | Transform [2] invalid for package [3]. Expected product version <= [4], found product version [5]. |
2749 | Transform [2] invalid for package [3]. Expected product version == [4], found product version [5]. |
2750 | Transform [2] invalid for package [3]. Expected product version >= [4], found product version [5]. |
2751 | Transform [2] invalid for package [3]. Expected product version > [4], found product version [5]. |
2752 | Could not open transform [2] stored as child storage of package [4]. |
2753 | The File '[2]' is not marked for installation. |
2754 | The File '[2]' is not a valid patch file. |
2755 | Server returned unexpected error [2] attempting to install package [3]. |
2756 | The property '[2]' was used as a directory property in one or more tables, but no value was ever assigned. |
2757 | Could not create summary info for transform [2]. |
2758 | Transform [2] doesn't contain a MSI version. |
2759 | Transform [2] version [3] incompatible with engine; Min: [4], Max: [5]. |
2760 | Transform [2] invalid for package [3]. Expected upgrade code [4], found [5]. |
2761 | Cannot begin transaction. Global mutex not properly initialized. |
2762 | Cannot write script record. Transaction not started. |
2763 | Cannot run script. Transaction not started. |
2769 | Custom Action [2] did not close [3] MSIHANDLEs. | Available with Windows Installer version 1.5 and later.
2801 | Unknown Message -- Type [2]. No action is taken |
2802 | No publisher is found for the event [2] |
2803 | Dialog View did not find a record for the dialog [2] |
2804 | On activation of the control [3] on dialog [2] CMsiDialog failed to evaluate the condition [3] |
2805 |  |
2806 | The dialog [2] failed to evaluate the condition [3] |
2807 | The action [2] is not recognized |
2808 | Default button is illdefined on dialog [2] |
2809 | On the dialog [2] the next control pointers do not form a cycle.There is a pointer from [3] to [4], but there is no further pointer |
2810 | On the dialog [2] the next control pointers do not form a cycle.There is a pointer from both [3] and [5] to [4] |
2811 | On dialog [2] control [3] has to take focus, but it is unable to do so |
2812 | The event [2] is not recognized |
2813 | The EndDialog event was called with the argument [2], but the dialog has a parent |
2814 | On the dialog [2] the control [3] names a non-existent control [4] as the next control |
2815 | ControlCondition table has a row without condition for the dialog [2] |
2816 | The EventMapping table refers to an invalid control [4] on dialog [2] for the event [3] |
2817 | The event [2] failed to set the attribute for the control [4] on dialog [3] |
2818 | In the ControlEvent table EndDialog has an unrecognized argument [2] |
2819 | Control [3] on dialog [2] needs a property linked to it |
2820 | Attempted to initialize an already initialized handler |
2821 | Attempted to initialize an already initialized dialog: [2] |
2822 | No other method can be called on dialog [2] untill all the controls are added |
2823 | Attempted to initialize an already initialized control: [3] on dialog [2] |
2824 | The dialog attribute [3] needs a record of at least [2] field(s) |
2825 | The control attribute [3] needs a record of at least [2] field(s) |
2826 | Control [3] on dialog [2] extends beyond the boundaries of the dialog [4] by [5] pixels |
2827 | The button [4] on the radiobutton group [3] on dialog [2] extends beyond the boundaries of the group [5] by [6] pixels |
2828 | Tried to remove control [3] from dialog [2], but the control is not part of the dialog |
2829 | Attempt to use an uninitialized dialog |
2830 | Attempt to use an uninitialized control on dialog [2] |
2831 | The control [3] on dialog [2] does not support [5] the attribute [4] |
2832 | The dialog [2] does not support the attribute [3] |
2833 | Control [4] on dialog [3] ignored the message [2] |
2834 | The next pointers on the dialog [2] do not form a single loop |
2835 | The control [2] was not found on dialog [3] |
2836 | The control [3] on the dialog [2] can not take focus |
2837 | The control [3] on dialog [2] wants the winproc to return [4] |
2838 | The item [2] in the selection table has itself as a parent |
2839 | Setting the property [2] failed |
2840 | Error dialog name mismatch |
2841 | No OK button was found on the error dialog |
2842 | No text field was found on the error dialog |
2843 | The ErrorString attribute is not supported for standard dialogs |
2844 | Can not execute an error dialog if the errorstring is not set |
2845 | The total width of the buttons exceeds the size of the error dialog |
2846 | SetFocus did not find the required control on the error dialog |
2847 | The control [3] on dialog [2] has both the icon and the bitmap style set |
2848 | Tried to set control [3] as the default button on dialog [2], but the control does not exist |
2849 | The control [3] on dialog [2] is of a type, that can not be integer valued |
2850 | Unrecognized volume type |
2851 | The data for the icon [2] is not valid |
2852 | At least one control has to be added to dialog [2] before it is used |
2853 | Dialog [2] is a modeless dialog. The execute method should not be called on it |
2854 | On the dialog [2] the control [3] is designated as first active control, but there is no such control |
2855 | The radiobutton group [3] on dialog [2] has fewer than 2 buttons |
2856 | Creating a second copy of the dialog [2] |
2857 | The directory [2] is mentioned in the selection table but not found |
2858 | The data for the bitmap [2] is not valid |
2859 | Test error message |
2860 | Cancel button is illdefined on dialog [2] |
2861 | The next pointers for the radiobuttons on dialog [2] control [3] do not form a cycle |
2862 | The attributes for the control [3] on dialog [2] do not define a valid icon size. Setting the size to 16 |
2863 | The control [3] on dialog [2] needs the icon [4] in size [5]x[5], but that size is not available. Loading the first available size |
2864 | The control [3] on dialog [2] received a browse event, but there is no configurable directory for the present selection. Likely cause: browse button is not authored correctly |
2865 | Control [3] on billboard [2] extends beyond the boundaries of the billboard [4] by [5] pixels |
2866 | The dialog [2] is not allowed to return the argument [3] |
2867 | The error dialog property is not set |
2868 | The error dialog [2] does not have the error style bit set |
2869 | The dialog [2] has the error style bit set, but is not an error dialog |
2870 | The help string [4] for control [3] on dialog [2] does not contain the separator character |
2871 | The [2] table is out of date: [3] |
2872 | The argument of the CheckPath control event on dialog [2] is invalid | Where "CheckPath" can be the CheckTargetPath, SetTargetPath or the CheckExistingTargetPath control events.
2873 | On the dialog [2] the control [3] has an invalid string length limit: [4] |
2874 | Changing the text font to [2] failed |
2875 | Changing the text color to [2] failed |
2876 | The control [3] on dialog [2] had to truncate the string: [4] |
2877 | The binary data [2] was not found |
2878 | On the dialog [2] the control [3] has a possible value: [4]. This is an invalid or duplicate value. |
2879 | The control [3] on dialog [2] can not parse the mask string: [4] |
2880 | Do not perform the remaining control events. |
2881 | CMsiHandler initialization failed |
2882 | Dialog window class registration failed |
2883 | CreateNewDialog failed for the dialog [2] |
2884 | Failed to create a window for the dialog [2]! |
2885 | Failed to create the control [3] on the dialog [2] |
2886 | Creating the [2] table failed |
2887 | Creating a cursor to the [2] table failed |
2888 | Executing the [2] view failed |
2889 | Creating the window for the control [3] on dialog [2] failed |
2890 | The handler failed in creating an unitialized dialog |
2891 | Failed to destroy window for dialog [2] |
2892 | [2] is an integer only control, [3] is not a valid integer value |
2893 | The control [3] on dialog [2] can accept property values that are at most [5] characters long. The value [4] exceeds this limit, and has been truncated. |
2894 | Loading RichEd20.dll failed. GetLastError() returned: [2] |
2895 | Freeing RichEd20.dll failed. GetLastError() returned: [2] |
2896 | Executing action [2] failed. |
2897 | Failed to create any [2] font on this system. |
2898 | For [2] textstyle, the system created a '[3]' font, in [4] character set. |
2899 | Failed to create [2] textstyle. GetLastError() returned: [3]. | Only available with Windows Installer version 1.1.
2901 | Invalid parameter to operation [2]: Parameter [3] |
2902 | Operation [2] called out of sequence. |
2903 | The file [2] is missing |
2904 | Could not BindImage file [2]. |
2905 | Could not read record from script file [2]. |
2906 | Missing header in script file [2]. |
2907 | Could not create secure security descriptor. Error: [2] |
2908 | Could not register component [2]. |
2909 | Could not unregister component [2]. |
2910 | Could not determine user's security id. |
2911 | Could not remove the folder [2]. |
2912 | Could not schedule file [2] for removal on reboot. |
2919 | No cabinet specified for compressed file: [2] |
2920 | Source directory not specified for file [2]. |
2924 | Script [2] version unsupported. Script version: [3], minimum version: [4], maximum version: [5]. |
2927 | ShellFolder id [2] is invalid. |
2928 | Exceeded maximum number of sources. Skipping source '[2]'. |
2929 | Could not determine publishing root. Error: [2] |
2932 | Could not create file [2] from script data. Error: [3] |
2933 | Could not initialize rollback script [2]. |
2934 | Could not secure transform [2]. Error [3] |
2935 | Could not un-secure transform [2]. Error [3] |
2936 | Could not find transform [2]. |
2937 | The Windows Installer cannot install a system file protection catalog. Catalog: [2], Error: [3] | Only available with Windows Installer version 1.2.
2938 | The Windows Installer cannot retrieve a system file protection catalog from the cache. Catalog: [2], Error: [3] | Only available with Windows Installer version 1.2.
2939 | The Windows Installer cannot delete a system file protection catalog from the cache. Catalog: [2], Error: [3] | Only available with Windows Installer version 1.2.
2940 | Directory Manager not supplied for source resolution. | Only available with Windows Installer version 1.5 and later.
2941 | Failed to check CRC for file [2]. | Only available with Windows Installer version 1.5 and later.
2942 | BindImage action has not been executed on [2] file. | Only available with Windows Installer version 1.5 and later.
2943 | This version of Windows does not support deploying 64-bit packages. The script [2] is for a 64-bit package. | Only available with Windows Installer version 1.5 and later.


Error Codes

These error codes are returned by the Windows Installer API, MsiExec.exe, and InstMsi.exe. Note that any error in Winerror.h (such as ERROR_INVALID_DATA, included here) can be returned as well.

Error Code | Value | Description
ERROR_SUCCESS | 0 | Action completed successfully.
ERROR_INVALID_DATA | 13 | The data is invalid.
ERROR_INVALID_PARAMETER | 87 | One of the parameters was invalid.
ERROR_INSTALL_SERVICE_FAILURE | 1601 | The Windows Installer service could not be accessed. Contact your support personnel to verify that the Windows Installer service is properly registered.
ERROR_INSTALL_USEREXIT | 1602 | User cancel installation.
ERROR_INSTALL_FAILURE | 1603 | Fatal error during installation.
ERROR_INSTALL_SUSPEND | 1604 | Installation suspended, incomplete.
ERROR_UNKNOWN_PRODUCT | 1605 | This action is only valid for products that are currently installed.
ERROR_UNKNOWN_FEATURE | 1606 | Feature ID not registered.
ERROR_UNKNOWN_COMPONENT | 1607 | Component ID not registered.
ERROR_UNKNOWN_PROPERTY | 1608 | Unknown property.
ERROR_INVALID_HANDLE_STATE | 1609 | Handle is in an invalid state.
ERROR_BAD_CONFIGURATION | 1610 | The configuration data for this product is corrupt. Contact your support personnel.
ERROR_INDEX_ABSENT | 1611 | Component qualifier not present.
ERROR_INSTALL_SOURCE_ABSENT | 1612 | The installation source for this product is not available. Verify that the source exists and that you can access it.
ERROR_INSTALL_PACKAGE_VERSION | 1613 | This installation package cannot be installed by the Windows Installer service. You must install a Windows service pack that contains a newer version of the Windows Installer service.
ERROR_PRODUCT_UNINSTALLED | 1614 | Product is uninstalled.
ERROR_BAD_QUERY_SYNTAX | 1615 | SQL query syntax invalid or unsupported.
ERROR_INVALID_FIELD | 1616 | Record field does not exist.
ERROR_INSTALL_ALREADY_RUNNING | 1618 | Another installation is already in progress. Complete that installation before proceeding with this install.
ERROR_INSTALL_PACKAGE_OPEN_FAILED | 1619 | This installation package could not be opened. Verify that the package exists and that you can access it, or contact the application vendor to verify that this is a valid Windows Installer package.
ERROR_INSTALL_PACKAGE_INVALID | 1620 | This installation package could not be opened. Contact the application vendor to verify that this is a valid Windows Installer package.
ERROR_INSTALL_UI_FAILURE | 1621 | There was an error starting the Windows Installer service user interface. Contact your support personnel.
ERROR_INSTALL_LOG_FAILURE | 1622 | Error opening installation log file. Verify that the specified log file location exists and is writable.
ERROR_INSTALL_LANGUAGE_UNSUPPORTED | 1623 | This language of this installation package is not supported by your system.
ERROR_INSTALL_TRANSFORM_FAILURE | 1624 | Error applying transforms. Verify that the specified transform paths are valid.
ERROR_INSTALL_PACKAGE_REJECTED | 1625 | This installation is forbidden by system policy. Contact your system administrator.
ERROR_FUNCTION_NOT_CALLED | 1626 | Function could not be executed.
ERROR_FUNCTION_FAILED | 1627 | Function failed during execution.
ERROR_INVALID_TABLE | 1628 | Invalid or unknown table specified.
ERROR_DATATYPE_MISMATCH | 1629 | Data supplied is of wrong type.
ERROR_UNSUPPORTED_TYPE | 1630 | Data of this type is not supported.
ERROR_CREATE_FAILED | 1631 | The Windows Installer service failed to start. Contact your support personnel.
ERROR_INSTALL_TEMP_UNWRITABLE | 1632 | The temp folder is either full or inaccessible. Verify that the temp folder exists and that you can write to it.
ERROR_INSTALL_PLATFORM_UNSUPPORTED | 1633 | This installation package is not supported on this platform. Contact your application vendor.
ERROR_INSTALL_NOTUSED | 1634 | Component not used on this machine
ERROR_PATCH_PACKAGE_OPEN_FAILED | 1635 | This patch package could not be opened. Verify that the patch package exists and that you can access it, or contact the application vendor to verify that this is a valid Windows Installer patch package.
ERROR_PATCH_PACKAGE_INVALID | 1636 | This patch package could not be opened. Contact the application vendor to verify that this is a valid Windows Installer patch package.
ERROR_PATCH_PACKAGE_UNSUPPORTED | 1637 | This patch package cannot be processed by the Windows Installer service. You must install a Windows service pack that contains a newer version of the Windows Installer service.
ERROR_PRODUCT_VERSION | 1638 | Another version of this product is already installed. Installation of this version cannot continue. To configure or remove the existing version of this product, use Add/Remove Programs on the Control Panel.
ERROR_INVALID_COMMAND_LINE | 1639 | Invalid command line argument. Consult the Windows Installer SDK for detailed command line help.
ERROR_INSTALL_REMOTE_DISALLOWED | 1640 | Installation from a Terminal Server client session not permitted for current user.
ERROR_SUCCESS_REBOOT_INITIATED | 1641 | The installer has started a reboot. This error code not available on Windows Installer version 1.0.
ERROR_PATCH_TARGET_NOT_FOUND | 1642 | The installer cannot install the upgrade patch because the program being upgraded may be missing or the upgrade patch updates a different version of the program. Verify that the program to be upgraded exists on your computer and that you have the correct upgrade patch. This error code is not available on Windows Installer version 1.0.
ERROR_SUCCESS_REBOOT_REQUIRED | 3010 | A reboot is required to complete the install. This does not include installs where the ForceReboot action is run. This error code not available on Windows Installer version 1.0.


Topic Not Found

No matching topic was found. Some possible reasons and remedies are as follows:

  • The file (.chm) that contains the destination topic is not in the expected location.

    Remedy: Rerun the MSDN Library Setup.

  • The file (.chm) that contains the current topic or destination topic is out-of-date and the link is no longer valid.

    Remedy: Install the latest version of the MSDN Library.

  • The MSDN Library CD is not in the CD-ROM drive.

    Remedy: Insert the MSDN Library CD into the CD-ROM drive.


Requirements

Many topics that introduce the syntax of an API element contain information about the build and run-time requirements for using the element. The format is as follows:

Windows NT/2000: Requires Windows NT 3.1 or later.
Windows 95/98: Requires Windows 95 or later.
Windows CE: Requires version 1.0 or later.
Header: Declared in winuser.h.
Import Library: Use user32.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000.

The first line indicates the versions of Windows NT on which an element is supported. This information may include required service packs, option packs, or components such as Internet Explorer. If an element is not supported, the line reads "Windows NT/2000: Unsupported."

The second line indicates whether an element is supported on Windows 95 or Windows 98. This information may include required OEM service releases, redistributables, or components such as Internet Explorer. If an element is not supported, the line reads "Windows 95/98: Unsupported."

The third line indicates the versions of Windows CE on which an element is supported. If an element is not supported, the line reads "Windows CE: Unsupported."

The fourth line indicates the file that defines an element. This value can be an .h file, .idl file, or .odl file. If the header file is supplied by the user, the line reads "Header: User-defined."

The fifth line indicates the file used to resolve calls to a function or member. This value can be a .lib file, .dll file, or .tlb file. If the import library is supplied by the user, the line reads "Import Library: User-defined." For element types that do not require an import library, this line is omitted.

The sixth line indicates whether an element exists as both a Unicode (W) version and an ANSI (A) version. If Unicode support is not available, this line is omitted.