Legal Information

[This is preliminary documentation and subject to change.]

Windows Installer Programmer's Reference

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 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. The names of companies, products, people, characters, and/or data mentioned herein are fictitious and are in no way intended to represent any real individual, company, product, or event, unless otherwise noted. Complying with all applicable copyright laws is the responsibility of the user. No part of this document may be reproduced or transmitted in any form or by any means, electronic or mechanical, for any purpose, without the express written permission of Microsoft Corporation.

Portions of this document specify and accompany software that is still in development. Some of the information in this documentation may be inaccurate or may not be an accurate representation of the functionality of final documentation or software. Microsoft assumes no responsibility for any damages that might occur directly or indirectly from these inaccuracies.

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.

© 1985-1998 Microsoft Corporation. All rights reserved.

ActiveX, BackOffice, DirectX, JScript, Microsoft, Microsoft Press, MS, MS-DOS, MSDN, Visual Basic, Visual C++, Windows, Win32, Win32s, and Windows NT are either registered trademarks or trademarks of Microsoft Corporation in the United States and/or other countries. OS/2 is a registered trademark licensed to Microsoft Corporation.

Other product and company names mentioned herein may be the trademarks of their respective owners.


Roadmap to Windows Installer Documentation

The Microsoftâ Windows® installer documentation contains general sections that provide useful information to all developers as well as sections that apply to particular tasks and audiences. To help you find the information you need, the following list describes each section of the installer documentation:

  • About Windows Installer contains high-level information useful to all developers.
  • Using Windows Installer contains a sample application and procedures that use the installer service functions.
  • Installer Function Reference contains reference material for the installer service functions. These functions access an installer package to install and manage an application.
  • Installer Package Programmer's Reference contains overview and reference material for developers who create or modify an installer package. This section is primarily for developers writing tools to create packages for application developers using the new installer. The information is also useful for application developers and administrators who want to modify the installer package and installation process through custom actions.


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. The topics in this section cover the major areas of functionality of the installer, such as:

  • Just-In-Time installation
  • Advertising applications and features
  • Components and features
  • Merges and transforms
  • Installation mechanism

For procedures and a sample application that use installer functions, see Using Windows Installer.


Just-In-Time Installation

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

Just-in-time installation makes it possible to offer functionality to users and applications in the absence of the files themselves. This notion is known as advertising. The Microsoft® Windows® installer has the capability of advertising functionality and to make just-in-time installations of application features or entire products. Whenever a user or application activates an advertised feature or product the installer proceeds with an installation of the needed components. This speeds up and 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 will call 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 will call the installer to enact a just-in-time product level installation.

For more information about how the installer enacts product and feature level installations see the section Advertising Applications and Features.

Advertisement and just-in-time installation 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 will appear to these users and a just-in-time installation will only be activated if another application activates the published application.

For more information about the two types of advertising see the section Assigning and Publishing.

For information on starting an application for the first time, see Initializing An Application.


Advertising Applications and Features

The Microsoft® Windows® installer supports advertising of applications and features. Advertising is a mechanism whereby an application that is not installed can however be accessed as though it were installed. Only the registry entries and other necessary information are placed on the local computer. When a user activates an advertised application the installer automatically installs the necessary components as described in Just-In-Time Installation.

The installer can access an advertised feature of an installed product without the support of the user's operating system by enacting a feature level installation. The installer however does require the support of the operating system to access an advertised product that has not yet been installed, and in this case the installer must enact a product level installation.

There are two types of advertising known as 'assigning' and 'publishing.' Assigning an application populates the user interface and the application appears essentially installed to the user. Publishing, by contrast, does not populate the user interface. Another application on the user's machine however can activate the published application. The distinction between assigning and publishing is a central part of the installer's capability to enhance system management. For more information about the two types of advertising see the section Assigning and Publishing.


Feature Level Installation

The figure above illustrates a feature level install that is enacted when a user requests the advertised functionality of an installed application. Because the application is installed it can call the installer's API on the user's behalf and have the requested feature installed. The installer then queries the system to return the current state of the feature. Finally, the installer installs of any missing components required by the feature and returns a path to the components back to the application.


Product Level Installation

The figure above illustrates the interaction between the operating system, the installer service, and an uninstalled advertised product during a product level installation. Because an uninstalled product cannot call the installer itself, the installation of the product requires that the operating system employ the installer's API. It is therefore possible to advertise an entire product when using the installer with Windows NT 5.0 because both OLE and the Shell make use of the installer's API. As illustrated in the figure, when a user activates the advertised product from an entry point the operating system calls the installer to install the product. After the installation is completed the installer returns a path to the now installed product back to the operating system which then launches the application.

Product level installation is a central part of the installer's capability of supporting system management by using assigning and publishing.


Assigning and Publishing

The two types of advertising are assigning and publishing. An application appears installed to a user when that application is assigned to the user. That is, the Start menu contains the appropriate shortcuts, icons are present, 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 as described in Just-In-Time Installation.

Publishing, by contrast, does not populate the user interface. However, if another application attempts to open the published application there is enough information present to install the application. A published application can also be opened through its file association or Multipurpose Internet Mail Extension (MIME) type. A user could also start the installation on demand by using a list of published applications that has been authored into the installer package.

Assigning and publishing enables an administrator to make applications required or optional to different groups of users. Published applications do not overwrite file associations of assigned applications, so optional applications do not interfere with required applications. This is a central part of how the installer can be used to improve system management.


System Management

A number of system management benefits result from applications using the installer.

An administrator can use the installer to tailor an installation to the user's specific needs. Only those features that are useful for a group of users need to be available in the user interface. These features can be upgraded by the administrator without the user's intervention or knowledge.

The management API enables the installer to manage all file paths on behalf of a product or application. An application using the installer can ask the service for a path to a given component at runtime. This frees applications from dependency on static file paths which often change between machines and can sometimes point to missing files.

An application using the installer can populate its user interface with features that are run locally or from the source with little or no visible difference to the user. An application runs identically regardless of the actual installation state because the installer resolves component file locations by querying the installation database. It can in some cases be more efficient to run a feature from the source instead of locally.

The installer can remove unused features from the local hard drive, as well as install features on demand, because the installer increments a usage count when applications request features. Applications therefore can keep track of usage statistics and request that the installer remove components that are not being used. Because the installer database is system-wide, the installer can keep usage counts of a feature for all client applications.


Components and Features

A Microsoft® Windows® installer application consists of features and components. A feature is a building-block of an application from the user's perspective. A component is a building-block of an application from the programmer's perspective. You can use this system of separating applications into components and features to make installation and system management transparent to the user.

A feature is a specific capability of an application as seen from the user's perspective. For example, a feature could be a spell-checker, thesaurus or a group of clip-art. Users want to know what they can do with a program; they are not concerned about the constraints under which you build the application. In other words, users do not care how you actually separate the program into pieces. You can structure features into a hierarchy so that when a child feature is installed, the parent feature is installed as well.

A component, in contrast, is how you break down an application. Examples of components are a group of related files, a COM object, or a library.

When a user selects clip-art files from a feature list, the associated component is installed. The component could be a viewer and a indexer for the clip-art.

Deciding how to separate an application into components involves a trade-off between performance and resiliency. Each component has a KeyPath associated with it. This KeyPath can be a file, registry key, or blank which indicates a directory. When a component is used, the installer checks the existence of the KeyPath. If the KeyPath is in its proper location, the installer assumes that the entire component is installed correctly. Thus if you use many small components, the installer checks the validity of the installation thoroughly, but checking many files can slow your application.

The relationship between features and components also defines the pieces in which an application is installed. From the user's perspective applications are installed one feature at a time; however, the installer resolves these features into components to actually carry out the installation. In other words, applications are installed component-by-component from the operating system's perspective, and installed feature-by-feature from a user's perspective.

While a many-to-many relationship between features and components is possible, the mechanism is most efficient when the relationship is as one-to-one as possible. It is possible for a component to map to more than one feature, but all parts of the component should do this together. Components are associated with a single folder. All files that are part of a component must reside in the same folder. Also, all parts of a component, whether they are registry entries or files are installed together. Thus, if your proposed component has portions with different setup logic, you must break the component into smaller pieces.

A feature can use the facilities of one or more components just as a component can be used by more than one feature. In addition, features can have their own hierarchical structure. This makes it easier to install groups of related features together.

For more information on using features, see the Feature Request Model and Requesting a Feature. For more information on separating an application into features and components, see Separating an Application into Features and Separating an Application into Components.


Separating an Application into Features

One of the most important aspects of making an application work effectively with the new installer is separating the application into features and components. For information on separating an application into components, see Separating an Application into Components. For more information on features, see Components and Features.

If you answer no to one or more of the following questions, you might want to reconsider identifying that aspect of your application a feature:

  • Does the feature present a single functionality to the user?
  • Does it make sense to install the feature by itself?
  • Conversely, does it make sense to install the entire feature at once?
  • Might an administrator want to make the feature available or unavailable depending on the needs of groups of users?


Separating an Application into Components

One of the most important aspects of making an application work effectively with the installer is separating the application into features and components. For information on separating an application into features, see Separating an Application into Features. For more information on components, see Components and Features.

If you answer no to any of these questions, you should consider separating the application into components differently:

  • Do your application's features and components have a close relationship?
  • Do all parts of the component map to a common feature?
  • Do all files of a component have a common installation location?
  • Do all parts of the component have a common setup logic?


Feature Request Model

As you write applications for the installer environment, remember that the file locations and installation state of features are flexible. Because a particular installation can access the files from a variety of locations, the application benefits most from the flexibility the installer provides if the application always requests features from the installer. Requesting features from the installer provides the added advantage of accurately maintained usage metrics. For a procedure that shows how to request a feature, see Requesting a Feature.

If the application calls MsiUseFeature before the application accesses a feature, the installer maintains usage metrics. One way an application might use this information is to remove a rarely used feature from the hard drive or to move a frequently used feature from the source medium to the local hard drive.

To request features in the installer, use MsiEnumFeatures, MsiQueryFeatureState, MsiUseFeature, MsiGetFeatureUsage, MsiConfigureFeature, and MsiGetComponentPath as shown in the following diagram.


Component Management

As well as being an installation technology, the installer manages the complex array of components found in applications. The installer saves system state to track everything needed for an application to install and run smoothly. It can resolve which applications require a particular component, which files make up that component, and where those files are. The installer can also determine when a file is no longer needed and can safely remove it, reducing wasted disk space.

There is also an installation database that describes how to install an application in any situation. This database includes tables for registry entries, directory structure, components, features, files, installation sequence, dialog boxes, and controls. For example, if an application requests a particular feature (for more information, see Requesting a Feature), and the application requests the installer to install the feature, the installer runs a query that resolves issues such as:

  • Which components belong to that feature
  • Which files belong to the components
  • Which registry entries need to be changed
  • Which actions need to be performed

This process is shown in the following illustration.

The installer also enables the application to keep usage metrics on components. So, when a component is not being used, it can be taken off the hard drive, further reducing the disk space requirements. For a stand-alone user, this method can eliminate the usual installation process; this user can simply start using a new application. As features are used, components are migrated off the installation medium and onto the hard drive. After a time, the optimal configuration for that user is locally available. Only the components used regularly take up any disk space. Because installations can become much more efficient, developers are free to incorporate more features without the risk of complicating the setup procedure, or taking up too much disk space.


Resiliency

Another benefit of installer component management capabilities is the added resiliency available to applications.

Because applications have become more complex, they can be prone to difficulties. For example, components can be deleted by a user or even another application, files can become corrupt, components can be replaced with incompatible versions. The installer provides applications the capability to recover gracefully from such situations without presenting the user with error messages. If the installer is unsuccessful at providing a component, the application can respond in the following ways:

  • Attempt to repair the file if it has become corrupted.
  • Reinstall the feature according to one of a number of possible criteria. For example, you can choose to reinstall a feature only if the current version is older than the version available on the source or only if the current file is corrupt in some manner. For information on installing, see Installing an Application. For information on reinstalling, see Reinstalling a Feature or Application.
  • Reinstall aspects of an application, such as shortcuts and registry entries.

Another way that applications can fail is that the resources the applications require are unavailable. Applications that rely on network resources for just-in-time installation are especially susceptible to such failures. However, the installer has also implemented a resiliency feature known as the source list. The source list contains the locations that the installer searches 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.

If an application utilizes these resiliency methods, a great number of recovery methods must fail before the user is presented with an error message.


Merges and Transforms

Because Microsoft® Windows® installer uses a relational database, you can manipulate the installation process by applying transform and merge operations to the installation database. A transform makes changes to some of the elements of a single database, for example, a transform can be used to change the language in the user interface of an application. A merge combines two databases into a single database. This means that the installation database for a component of the application can be developed separately and then later merged into the main installation database. By using multiple transforms and merges together, the user gains much more control over the installation process with the installer than is possible with other installation technologies.

Primary uses for transforms include:

  • Customizing 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.

  • Synchronizing applications across different languages

    Transforms are useful for keeping packages authored at widely separated locations in synchronization 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.

  • Patching applications

    Transforms can be employed to apply a minor fix to an application that does not warrant a major upgrade.

Merges are useful to development teams because they allow a large application to be divided into smaller parts that can be recombined later.

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

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

Multiple transforms and merges 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.


Installation Mechanism

There are two phases of an installation process: acquisition and execution. A rollback phase may also occur if the installation is unsuccessful.

The exact installation procedure is determined during the acquisition phase. At the beginning of the acquisition phase, an application or a user instructs Microsoft® Windows® installer to install a feature or an application. The installer complies with this request by beginning the required action sequence. The actions query the database and generate a script that gives a step-by-step procedure for performing the installation. For information on installing an application, see Initializing an Application and Installing an Application.

During the execution phase, the installer passes the information to a process with elevated privileges to generate an installation script. The process with elevated privileges then runs the script. On a secure system, this gives a user with limited privileges the ability to instigate an installation without compromising system integrity.

If an installation is unsuccessful, the installer automatically 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 called Config.msi. Once the installation is complete, the rollback script and the saved files are deleted.


Using Windows Installer

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 a sample application and procedures that explain how to implement installer functionality in your application:

  • Sample application for the installer
  • Initializing an application
  • Getting application information
  • Requesting a feature
  • Installing an application
  • Reinstalling a feature or application
  • Installing a missing component
  • Upgrading a Feature or Application by Patching


Initializing an Application

To enable the Microsoft® Windows® installer functionality, there are a number of functions an application must call when it is initializing. 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 can call 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.

For more information on initializing an application, see Initializing an Application and Installation Mechanism.


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.

The following steps describe how to get product information:

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. For more information on feature requests, see the Feature Request Model in Components and Features.

The following steps describe how your application requests a feature:

To request a feature
  1. Indicate your application's intent to use a feature by calling the MsiUseFeature function.
  2. Determine file locations by calling the MsiGetComponentPath function.
  3. Configure the feature by calling the MsiConfigureFeature function.
  4. Obtain usage metrics by calling the MsiGetFeatureUsage function.

You can also use the MsiProvideComponent or the MsiProvideQualifiedComponent function to request a feature. However, because these functions increment the usage count, use them with caution to prevent inaccurate usage counts.


Installing an Application

You can install entire products with Microsoft® 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 MsiConfigureProduct function to configure an individual component.

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


Reinstalling a Feature or Application

Microsoft® 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.

The following list contains several means 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
  1. Call MsiReinstallProduct.
To reinstall a feature using the installer
  1. 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 on 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 totally missing should be reinstalled, or that only corrupted files (for example, any executable file whose checksum doesn't match the actual file contents) be replaced. Alternatively, you can specify that the fitness of the current installation be verified, without actually repairing any broken or missing files/registry entries. In this case, for all installed features, the installer reports (typically in a log file) the results of any verification that you specify, such as whether there are any missing or corrupt files, any files of the wrong version, or any missing or incorrect registry entries. At any later time, you can then run the installation again to repair any or all of the detected problems.


Upgrading a Feature or Application by Patching

Microsoft® Windows® installer can upgrade an existing application by patching. In the traditional form of an upgrade an entire new version of a product is installed over the old version. Patching is essentially an efficient form of an upgrade because only the individual file bits needed to update the application are changed. To the user this means that the same upgrade involves downloading a much smaller upgrade patch, rather than the entire product, and that customizations are preserved through the upgrade.

To apply an upgrade to a product by patching
  1. Specify the full path to the patch package containing the upgrade.

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

  3. Specify the path to the product package to receive the upgrade, or choose to have the patch applied to a group of applicable products specified in the Upgrade table. See previous paragraph.
  4. Call the MsiApplyPatch function.

'


Installing a Missing Component

If the MsiGetComponentPath function was successful, the key file is present, and the missing file must be a non-key file. Since Microsoft® Windows® installer installs features, not components, the installer resolves which component the file belongs to and installs the feature that requires the least disk space.

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

To install a missing component
  • Call the MsiInstallMissingComponent function if the feature associated with the component is unknown.

    Or

    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.


Sample Application for the Installer

This following simple application shows how to use many Microsoft® Windows® installer service functions. The sample application takes the package of an installed application at the command line and prints all of the features and components associated with the application.

#include <windows.h>
#include <msi.h>
#include <stdio.h>
#include <stdlib.h>

void ProcessError(UINT uiError,LPTSTR szFunctionName);

#define PATH_BUFFER_SIZE 10  // beginning buffer size for path
#define GUID_LENGTH 39       // includes terminating null

int main(int argc,char *argv[])
{
  DWORD iFeatureIndex=0;      // index for enumerating features
  DWORD iComponentIndex=0;    // index for enumerating components
  DWORD iProductIndex=0;      // index for enumerating products

  LPTSTR lpProductBuf;        // buffer for product code, string GUID
  LPTSTR lpComponentBuf;      // buffer for component code, GUID
  LPTSTR lpFeatureBuf;        // buffer for feature
  LPTSTR lpParentBuf;         // buffer for parent of feature
  LPTSTR lpPathBuf;           // the path to the databases
  LPTSTR lpTempProductBuf;

  MSIHANDLE hProduct;         // returned product handle, must be
                              // closed
  INSTALLSTATE isState;       // the install state returned by
                              // MsiGetComponentPath

  UINT uiError,uiError2;      // variable to receive errors

  DWORD cchProductBufLength;  // number of characters in lpProductBuf
  DWORD cchComponentBufLength;// number of characters in lpComponentBuf
  DWORD cchPathBufLength;     // number of characters in PathBuf

// allocating space for variables

  cchComponentBufLength=GUID_LENGTH;
  cchProductBufLength=GUID_LENGTH;
  cchPathBufLength=PATH_BUFFER_SIZE;

  lpFeatureBuf=(LPTSTR) calloc(MAX_FEATURE_CHARS,sizeof(char));
  lpParentBuf=(LPTSTR) calloc(MAX_FEATURE_CHARS,sizeof(char));
  lpPathBuf=(LPTSTR) calloc(PATH_BUFFER_SIZE,sizeof(char));

  lpProductBuf=(LPTSTR) calloc(GUID_LENGTH,sizeof(char));
  lpComponentBuf=(LPTSTR) calloc(GUID_LENGTH,sizeof(char));
  lpTempProductBuf=(LPTSTR) calloc(GUID_LENGTH,sizeof(char));

  /* determine the current path so that the user doesn't
have to type it in at the command line */

  cchPathBufLength=GetCurrentDirectory(
    cchPathBufLength,
    lpPathBuf);

  /* If the path variable isn't long enough for the path plus the package name, reallocate and try again */

  if(cchPathBufLength>PATH_BUFFER_SIZE+1+strlen(argv[1])){
    realloc(lpPathBuf,cchPathBufLength);
    if(cchPathBufLength>PATH_BUFFER_SIZE)
      GetCurrentDirectory(cchPathBufLength,lpPathBuf);
  }

  strcat(lpPathBuf,"\\");
  strcat(lpPathBuf,argv[1]);
  printf ("%s\n",lpPathBuf);

  // open the package

  uiError=MsiOpenPackage(lpPathBuf,&hProduct);

  // check for errors

  if (uiError!=ERROR_SUCCESS){
    ProcessError(uiError,"MsiOpenPackage");
    return uiError;
  }
  else
    printf("Package opened\n");

/* Many functions require the product code, so you obtain it from
the ProductCode property. After this function call, the package
is no longer used. All further information is obtained from the
configuration database */

  uiError=MsiGetProductProperty(hProduct,
    "ProductCode",
    lpProductBuf,
    &cchProductBufLength);

  /* Here you make sure that the product code is properly obtained.
If there isn't enough room in the variable, you reallocate and try
again. A while loop is used to ensure that MsiGetProductProperty
finally does return ERROR_SUCCESS */

  while (uiError!=ERROR_SUCCESS){
    if (ERROR_MORE_DATA==uiError){
      cchProductBufLength++;
      realloc(&lpProductBuf,cchProductBufLength);
      uiError=MsiGetProductProperty(hProduct,
        "ProductCode",
        lpProductBuf,
        &cchProductBufLength);
    }
    else{
      ProcessError(uiError,"MsiGetProductProperty");
      return uiError;
    }
  }

  printf("Product code obtained %s\n",lpProductBuf);

  // Here you enumerate all of the features associated with the product

  do{
    uiError=MsiEnumFeatures(lpProductBuf,
      iFeatureIndex,
      lpFeatureBuf,
      lpParentBuf);
    if(ERROR_SUCCESS==uiError){
      printf("Feature: %s\n Parent: %s\n",lpFeatureBuf,lpParentBuf);
      iFeatureIndex++;
    }
  } while (ERROR_SUCCESS==uiError);

  if(uiError!=ERROR_NO_MORE_ITEMS){
    ProcessError(uiError,"MsiEnumFeatures");
    return uiError;
  }

/* This section enumerates all of the installed components of a
product and prints a path to their locations. This is more
 complicated than enumerating the features. MsiEnumComponents
enumerates all of the components present on a particular computer,
regardless of associated product. You are only interested in the
components associated with the product given by the product code you
obtained above. Thus for each component enumerated, you enumerate the
products that use it. If the product matches the product you are
interested in, you find the path and print it.
You can use MsiLocateComponent instead of MsiGetComponentPath. In
fact MsiLocateComponent doesn't require the product code so you could
eliminate the MsiEnumClients call and list all of the components.
However, it is possible for two products to use the same component in
different locations. Without the product code, it is not possible for
the installer to know which path to return.  For this reason, it is
recommended that you use MsiGetComponentPath instead of
MsiLocateComponent. */

  do{
    uiError=MsiEnumComponents(iComponentIndex,lpComponentBuf);
    if (ERROR_SUCCESS==uiError){
      iProductIndex=0;
      do{
        uiError2=MsiEnumClients(lpComponentBuf,
          iProductIndex,
          lpTempProductBuf);
        if (!(uiError2==ERROR_SUCCESS||
          uiError2==ERROR_NO_MORE_ITEMS)){
          ProcessError(uiError2,"MsiEnumClients");
          return uiError2;
        }
        iProductIndex++;
        if(0==strcmp(lpTempProductBuf,lpProductBuf)){
          uiError2=ERROR_NO_MORE_ITEMS;
          isState=MsiGetComponentPath(lpProductBuf,
            lpComponentBuf,
            lpPathBuf,
            &cchPathBufLength);
          while (INSTALLSTATE_MOREDATA==isState){
            lpPathBuf=realloc(lpPathBuf,
              sizeof(char)*cchPathBufLength);
            isState=MsiGetComponentPath(lpProductBuf,
              lpComponentBuf,
              lpPathBuf,
              &cchPathBufLength);
          }
          switch (isState){
          case INSTALLSTATE_LOCAL:
            printf("Locally installed\n");
            break;
          case INSTALLSTATE_SOURCE:
            printf("Installed from source\n");
            break;
          case INSTALLSTATE_SOURCEABSENT:
            printf("Source not available\n");
            break;
          case INSTALLSTATE_DEFAULT:
            printf("Default install state\n");
            break;
          default:
            printf("installstate number:%d\n",isState);
            break;
          }
          printf("Component: %s\nPath: %s\n",lpComponentBuf,lpPathBuf);
        }
      }while(ERROR_SUCCESS==uiError2);
    }
    iComponentIndex++;
  } while (ERROR_SUCCESS==uiError);

  if(uiError!=ERROR_NO_MORE_ITEMS){
    ProcessError(uiError,"MsiEnumComponents");
    return uiError;
  }

  MsiCloseHandle(hProduct);
  return 0;
}

void ProcessError(UINT uiError,LPTSTR szFunctionName){

  printf("An error occurred in %s:",szFunctionName);

  switch (uiError){
  case ERROR_BAD_CONFIGURATION:
    printf("The configuration information is corrupt.\n");
    break;
  case ERROR_INSTALL_FAILURE:
    printf("The product could not be opened.\n");
    break;
  case ERROR_INVALID_HANDLE:
    printf("An invalid handle was passed to the function.\n");
    break;
  case ERROR_INVALID_PARAMETER:
    printf("An invalid parameter was passed.\n");
    break;
  case ERROR_UNKNOWN_PRODUCT:
    printf("The specified product is unknown.\n");
    break;
  case ERROR_ACCESS_DENIED:
    printf("Access is denied.\n");
    break;
  default:
    printf("Error number: %d\n",uiError);
    break;
  }
  return;
}


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

You can use the following user interface and logging functions in your application:

MsiSetInternalUI

MsiSetExternalUI

MsiEnableLog

Handle Management Functions

You can use the following handle management functions in your application:

MsiCloseHandle

MsiCloseAllHandles

Installation and Configuration Functions

You can use the following installation and configuration functions in your application:

MsiInstallProduct

MsiConfigureProduct

MsiReinstallProduct

MsiConfigureFeature

MsiReinstallFeature

MsiInstallMissingComponent

MsiInstallMissingFile

Component-Specific Functions

You can use the following functions to provide components in your application:

MsiProvideComponent

MsiProvideQualifiedComponent

You can use the following functions to locate components in your application. The state of the feature being used should have been checked previously:

MsiGetComponentPath

MsiLocateComponent

Application-Only Functions

Your application can use the following application-only functions:

MsiCollectUserInfo

MsiUseFeature

MsiGetProductCode

System Status Functions

You can use the following functions to query the status of the system:

MsiEnumProducts

MsiEnumFeatures

MsiEnumComponents

MsiEnumClients

MsiEnumComponentQualifiers

MsiQueryFeatureState

MsiQueryProductState

MsiGetFeatureUsage

MsiGetProductInfo

MsiGetUserInfo

Product Query Functions

You can use the following functions to query the product:

MsiOpenProduct

MsiOpenPackage

MsiGetProductProperty

MsiGetFeatureInfo

Patching Functions

You can use the following functions to patch existing products.

MsiApplyPatch

Database Access Reference 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 Access Reference 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 WINAPI 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 a product to be patched. This is an optional parameter and if omitted the patch is applied to every product listed in the patch package as eligible to receive the patch.
eInstallType
This parameter specifies the type of installation to patch. A value of 1 for INSTALLTYPE_NETWORK_IMAGE sets this for a network installation. The eInstallType parameter is ignored if szInstallPackage is omitted.
Type of Installation | Meaning
INSTALLTYPE_NETWORK_IMAGE | Indicates a network installation

szCommandLine
Specifies command line property settings.

Return Values

ERROR_SUCCESS
The function completed successfully.
ERROR_INSTALL_PACKAGE*
These errors may indicate an error with the patch package or the install package.
Any Action Error
An error relating to an action occurred.
Any Initialization Error
An error relating to initialization occurred.

QuickInfo

Windows NT: Requires version 4.0 or later. Available as a redistributable for Windows NT 4.0.
Windows: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Windows CE: Unsupported.
Header: Declared in msi.h.
Import Library: Use msi.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT.


MsiCloseAllHandles

The MsiCloseAllHandles function closes all open installation handles in the process. This is a diagnostic function and should not be used for cleanup.

UINT MsiCloseAllHandles();

Parameters

None

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 will only close handles allocated by the calling thread, and will not affect handles allocated by other threads, such as the install handle passed to custom actions.

QuickInfo

Windows NT: Requires version 4.0 or later. Available as a redistributable for Windows NT 4.0.
Windows: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Windows CE: Unsupported.
Header: Declared in msi.h.
Import 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

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.

QuickInfo

Windows NT: Requires version 4.0 or later. Available as a redistributable for Windows NT 4.0.
Windows: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Windows CE: Unsupported.
Header: Declared in msi.h.
Import 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
Specifies the product code of the product for which the user information is collected.

Return Values

ERROR_INVALID_PARAMETER
An invalid parameter was passed to the function.
ERROR_SUCCESS
The function succeeded.
Any Action Error
An error relating to an action occurred.
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 action.

QuickInfo

Windows NT: Requires version 4.0 or later. Available as a redistributable for Windows NT 4.0.
Windows: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Windows CE: Unsupported.
Header: Declared in msi.h.
Import Library: Use msi.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT.

See Also

Application-Only Functions


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
Specifies the product code for the product to be configured.
szFeature
Specifies the feature ID for the feature to be configured.
eInstallState
Specifies the installation state for the feature. This parameter must be one of the following values.
Value | Meaning
INSTALLSTATE_ADVERTISE | 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

ERROR_INVALID_PARAMETER
An invalid parameter was passed to the function.
ERROR_SUCCESS
The function succeeded.
Any Action Error
An error relating to an action occurred.
Any Initialization Error
An error relating to initialization occurred.

QuickInfo

Windows NT: Requires version 4.0 or later. Available as a redistributable for Windows NT 4.0.
Windows: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Windows CE: Unsupported.
Header: Declared in msi.h.
Import Library: Use msi.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT.

See Also

Installation and Configuration Functions


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
Specifies the product code for the product to be configured.
iInstallLevel
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
Specifies the installation state for the product. This parameter can be one of the following values.
Value | Meaning
INSTALLSTATE_LOCAL | The product is installed locally.
INSTALLSTATE_ABSENT | The product is uninstalled.
INSTALLSTATE_SOURCE | The product is installed to run from source.
INSTALLSTATE_DEFAULT | The product is installed to its default location.

Return Values

ERROR_INVALID_PARAMETER
An invalid parameter was passed to the function.
ERROR_SUCCESS
The function succeeded.
Any Action Error
An error relating to an action occurred.
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.

QuickInfo

Windows NT: Requires version 4.0 or later. Available as a redistributable for Windows NT 4.0.
Windows: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Windows CE: Unsupported.
Header: Declared in msi.h.
Import Library: Use msi.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT.

See Also

Installation and Configuration Functions


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
  BOOL fAppend         // value to indicate append mode
);

Parameters

dwLogMode
Specifies the log mode. This parameter can be one or more of the following values.
Value | Meaning
INSTALLLOGMODE_OUTOFMEMORY | The out-of-memory error messages are logged.
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_COMMONDATA | The parameters for user-interface initialization are logged.
INSTALLLOGMODE_RESERVED | Reserved for future use.
INSTALLLOGMODE_ACTIONSTART | The start of new installation actions are logged.
INSTALLLOGMODE_ACTIONDATA | The data record with the installation action is logged.
INSTALLLOGMODE_PROPERTYDUMP | The property values at termination are logged.
INSTALLLOGMODE_FILESINUSE | List of files that need to be replaced.

szLogFile
Specifies the string that holds the full path to the log file. The file is created if it does not exist.
fAppend
Specifies a Boolean value. This value is set to TRUE to append an existing file, and it is set to FALSE to replace the contents.

Return Values

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

QuickInfo

Windows NT: Requires version 4.0 or later. Available as a redistributable for Windows NT 4.0.
Windows: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Windows CE: Unsupported.
Header: Declared in msi.h.
Import Library: Use msi.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT.

See Also

Interface and Logging Functions


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
Specifies the component whose clients are to be enumerated.
iProductIndex
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
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

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).

QuickInfo

Windows NT: Requires version 4.0 or later. Available as a redistributable for Windows NT 4.0.
Windows: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Windows CE: Unsupported.
Header: Declared in msi.h.
Import Library: Use msi.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT.

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,      // in/out qualifier buffer character count
  LPTSTR lpApplicationDataBuf,  // buffer to return application-registered data
  DWORD *pcchApplicationDataBuf // in/out lpApplicationDataBuf character count
);

Parameters

szComponent
Specifies component whose qualifiers are to be enumerated.
iIndex
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
Pointer to a buffer that receives the qualifier code.
pcchQualifierBuf
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
Pointer to a buffer that receives the application registered data for the qualifier. This parameter can be NULL.
pcchApplicationDataBuf
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

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 products (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.

QuickInfo

Windows NT: Requires version 4.0 or later. Available as a redistributable for Windows NT 4.0.
Windows: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Windows CE: Unsupported.
Header: Declared in msi.h.
Import Library: Use msi.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT.

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
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
Pointer to a buffer that receives the component code.

Return Values

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 componets 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).

QuickInfo

Windows NT: Requires version 4.0 or later. Available as a redistributable for Windows NT 4.0.
Windows: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Windows CE: Unsupported.
Header: Declared in msi.h.
Import Library: Use msi.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT.

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
Specifies the product whose features are to be enumerated.
iFeatureIndex
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
Pointer to a buffer that receives the feature ID. Must be sized to hold a string of length MAX_FEATURE_CHARS.
lpParentBuf
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.

Return Values

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).

QuickInfo

Windows NT: Requires version 4.0 or later. Available as a redistributable for Windows NT 4.0.
Windows: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Windows CE: Unsupported.
Header: Declared in msi.h.
Import Library: Use msi.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT.

See Also

System Status Functions


MsiEnumProducts

The MsiEnumProducts function enumerates advertising products. The function retrieves one product code each time it is called.

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

Parameters

iProductIndex
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
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

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).

QuickInfo

Windows NT: Requires version 4.0 or later. Available as a redistributable for Windows NT 4.0.
Windows: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Windows CE: Unsupported.
Header: Declared in msi.h.
Import Library: Use msi.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT.

See Also

System Status Functions


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       // in/out buffer character count
);

Parameters

szProduct
Specifies the product code for the client product.
szComponent
Specifies the component ID of the component to be located.
lpPathBuf
Pointer to a variable that receives the path to the component. This parameter can be NULL.
pcchBuf
Pointer to a variable that specifies the size, in characters, of the buffer pointed to by the lpPathBuf parameter.

If lpPathBuf is NULL, pcchBuf can be NULL.

Return Values

ERROR_INSTALL_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.

QuickInfo

Windows NT: Requires version 4.0 or later. Available as a redistributable for Windows NT 4.0.
Windows: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Windows CE: Unsupported.
Header: Declared in msi.h.
Import Library: Use msi.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT.

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, // in/out buffer character count
  LPTSTR lpHelpBuf,    // description
  DWORD *pcchHelpBuf   // in/out buffer character count
);

Parameters

hProduct
Handle to the product that owns the feature. This handle is obtained from MsiOpenProduct.
szFeature
Specifies the feature code for the feature about which information should be returned.
lpAttributes
Specifies the attribute flags. Must be one or more of the following.
Flag | Value
INSTALLFEATUREATTRIBUTE_FAVORLOCAL | 1 << 0
INSTALLFEATUREATTRIBUTE_FAVORSOURCE | 1 << 1
INSTALLFEATUREATTRIBUTE_FOLLOWPARENT | 1 << 2
INSTALLFEATUREATTRIBUTE_FAVORADVERTISE | 1 << 3
INSTALLFEATUREATTRIBUTE_DISALLOWADVERTISE | 1 << 4

For information on how these flags work together, see the Feature table.

lpTitleBuf
Pointer to a buffer to receive the localized descriptive name of the feature.
pcchTitleBuf
As input, the size of lpTitleBuf. As output, the number of characters returned in lpTitleBuf.
lpHelpBuf
Pointer to a buffer to receive the localized descriptive name of the feature.
pcchHelpBuf
As input, the size of lpHelpBuf. As output, the number of characters returned in lpHelpBuf.

Return Values

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.

QuickInfo

Windows NT: Requires version 4.0 or later. Available as a redistributable for Windows NT 4.0.
Windows: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Windows CE: Unsupported.
Header: Declared in msi.h.
Import Library: Use msi.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT.

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
Specifies the product code for the product containing the feature.
szFeature
Specifies the feature code for the feature for which metrics are to be returned.
pdwUseCount
Indicates the number of times the feature has been used.
pwDateUsed
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

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.

QuickInfo

Windows NT: Requires version 4.0 or later. Available as a redistributable for Windows NT 4.0.
Windows: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Windows CE: Unsupported.
Header: Declared in msi.h.
Import Library: Use msi.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT.

See Also

System Status Functions


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
This parameter specifies the component code of a component that has been installed or advertised by the application. This will be typically the component code of the component containing the executable file of the application.
lpProductBuf
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

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.

QuickInfo

Windows NT: Requires version 4.0 or later. Available as a redistributable for Windows NT 4.0.
Windows: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Windows CE: Unsupported.
Header: Declared in msi.h.
Import Library: Use msi.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT.

See Also

Application-Only Functions


MsiGetProductInfo

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

INSTALLSTATE MsiGetProductInfo(
  LPCTSTR szProduct,   // product code
  LPCTSTR szProperty,  // product property
  LPTSTR lpValueBuf,   // buffer to return property value
  DWORD *pcchValueBuf  // in/out buffer character count,
                       // including NULL
);

Parameters

szProduct
Specifies the product code for the product.
szProperty
Specifies the property to be retrieved. The properties in the following list can only be retrieved from applications that are already installed.
Installed Properties | Description
INSTALLPROPERTY_INSTALLEDPRODUCTNAME | Installed product name
INSTALLPROPERTY_VERSIONSTRING | Product version
INSTALLPROPERTY_HELPLINK | Support link
INSTALLPROPERTY_HELPTELEPHONE | Support telephone
INSTALLPROPERTY_INSTALLLOCATION | Installation location
INSTALLPROPERTY_INSTALLSOURCE | Installation source
INSTALLPROPERTY_INSTALLDATE | Installation date
INSTALLPROPERTY_PUBLISHER | Publisher
INSTALLPROPERTY_LOCALPACKAGE | Local cached package
INSTALLPROPERTY_URLINFOABOUT | URL information
INSTALLPROPERTY_URLUPDATEINFO | URL update information
INSTALLPROPERTY_VERSIONMINOR | Minor product version
INSTALLPROPERTY_VERSIONMAJOR | Major product version
INSTALLPROPERTY_PACKAGECODE | Identifier of package product was installed from
INSTALLPROPERTY_VERSION Product

version

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

lpValueBuf
Pointer to a buffer that receives the property value. This parameter can be NULL.
pcchValueBuf
Pointer to a variable that specifies the size, in characters, of the buffer pointed to by the lpValueBuf parameter. This size should include the terminating NULL character.

If lpValueBuf is NULL, pcchValueBuf can be NULL.

Return Values

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.

QuickInfo

Windows NT: Requires version 4.0 or later. Available as a redistributable for Windows NT 4.0.
Windows: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Windows CE: Unsupported.
Header: Declared in msi.h.
Import Library: Use msi.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT.

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   // in/out buffer character count
);

Parameters

hProduct
Handle to the product obtained from MsiOpenProduct.
szProperty
Specifies the property to retrieve. This is case-sensitive.
lpValueBuf
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
Pointer to a variable that specifies the size, in characters, of the buffer pointed to by the lpValueBuf parameter. This size should include the terminating NULL character.

If lpValueBuf is NULL, pcchValueBuf can be NULL.

Return Values

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.

QuickInfo

Windows NT: Requires version 4.0 or later. Available as a redistributable for Windows NT 4.0.
Windows: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Windows CE: Unsupported.
Header: Declared in msi.h.
Import Library: Use msi.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT.

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, // in/out buffer character count,
                          // including NULL
  LPTSTR lpOrgNameBuf,    // buffer to return organization name
  DWORD *pcchOrgNameBuf,  // in/out buffer character count,
                          // including NULL
  LPTSTR lpSerialBuf,     // buffer to return product ID
  DWORD *pcchSerialBuf    // in/out buffer character count,
                          // including NULL
);

Parameters

szProduct
Specifies the product code for the product to be queried.
lpUserNameBuf
Pointer to a variable that receives the name of the user.
pcchUserNameBuf
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
Pointer to a buffer that receives the organization name.
pcchOrgNameBuf
Pointer to a variable that specifies the size, in characters, of the buffer pointed to by the lpOrgNameBuf parameter. This size should include the terminating null character.
lpSerialBuf
Pointer to a buffer that receives the product ID.
pcchSerialBuf
Pointer to a variable that specifies the size, in characters, of the buffer pointed to by the lpSerialBuf parameter. This size should include the terminating null character.

Return Values

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.

QuickInfo

Windows NT: Requires version 4.0 or later. Available as a redistributable for Windows NT 4.0.
Windows: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Windows CE: Unsupported.
Header: Declared in msi.h.
Import Library: Use msi.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT.

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
Specifies the product code for the product that owns the component to be installed.
szComponent
Identifies the component to be installed.
eInstallState
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

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.

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.

QuickInfo

Windows NT: Requires version 4.0 or later. Available as a redistributable for Windows NT 4.0.
Windows: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Windows CE: Unsupported.
Header: Declared in msi.h.
Import Library: Use msi.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT.


MsiInstallMissingFile

The MsiInstallMissingFile function installs files that are unexpectedly missing.

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

Parameters

szProduct
Specifies the product code for the product that owns the file to be installed.
szFile
Identifies the file to be installed.

Return Values

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.

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.

QuickInfo

Windows NT: Requires version 4.0 or later. Available as a redistributable for Windows NT 4.0.
Windows: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Windows CE: Unsupported.
Header: Declared in msi.h.
Import Library: Use msi.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT.

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
Specifies the path to the package.
szCommandLine
Specifies the command line property settings. This should be a list of the format Property=Setting Property=Setting.

Return Values

ERROR_SUCCESS
The function completed successfully.
Any Action Error
An error relating to an action occurred.
Any Initialization Error
An error relating to initialization occurred.

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.

QuickInfo

Windows NT: Requires version 4.0 or later. Available as a redistributable for Windows NT 4.0.
Windows: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Windows CE: Unsupported.
Header: Declared in msi.h.
Import Library: Use msi.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT.

See Also

Installation and Configuration Functions


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
Specifies the component ID of the component to be located.
lpPathBuf
Pointer to a variable that receives the path to the component. This parameter can be NULL.
pcchBuf
Pointer to a variable that specifies the size, in characters, of the buffer pointed to by the lpPathBuf parameter.

If lpPathBuf is NULL, pcchBuf can be NULL.

Return Values

ERROR_INSTALL_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.

QuickInfo

Windows NT: Requires version 4.0 or later. Available as a redistributable for Windows NT 4.0.
Windows: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Windows CE: Unsupported.
Header: Declared in msi.h.
Import Library: Use msi.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT.

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
Specifies the path to the package.
hProduct
Pointer to a variable that receives the product handle.

Return Values

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.

QuickInfo

Windows NT: Requires version 4.0 or later. Available as a redistributable for Windows NT 4.0.
Windows: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Windows CE: Unsupported.
Header: Declared in msi.h.
Import Library: Use msi.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT.

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
Specifies the product code of the product to be opened.
hProduct
Pointer to a variable that receives the product handle.

Return Values

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.

QuickInfo

Windows NT: Requires version 4.0 or later. Available as a redistributable for Windows NT 4.0.
Windows: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Windows CE: Unsupported.
Header: Declared in msi.h.
Import Library: Use msi.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT.

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
Specifies the product code for the product that contains the feature with the necessary component.
szFeature
Specifies the feature ID of the feature with the necessary component.
szComponent
Specifies the component code of the necessary component.
dwInstallMode
Defines the installation mode. This parameter can be one of the following values.
Value | Meaning
INSTALLMODE_DEFAULT | Provide the component, performing any installation, if necessary.
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.

lpPathBuf
Pointer to a variable that receives the path to the component. This parameter can be NULL.
pcchPathBuf
Pointer to a variable that specifies the size, in characters, of the buffer pointed to by the lpPathBuf parameter.

If lpPathBuf is NULL, pcchBuf can be NULL.

Return Values

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_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.

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

QuickInfo

Windows NT: Requires version 4.0 or later. Available as a redistributable for Windows NT 4.0.
Windows: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Windows CE: Unsupported.
Header: Declared in msi.h.
Import Library: Use msi.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT.

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
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
Specifies a qualifier into a list of advertising components (from PublishComponent Table).
dwInstallMode
Defines the installation mode. This parameter can be one of the following values.
Value | Meaning
INSTALLMODE_DEFAULT | Provide the component, performing any installation, if necessary.
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.

lpPathBuf
Pointer to a variable that receives the path to the component. This parameter can be NULL.
pcchPathBuf
Pointer to a variable that specifies the size, in characters, of the buffer pointed to by the lpPathBuf parameter.

If lpPathBuf is NULL, pcchBuf can be NULL.

Return Values

ERROR_INDEX_ABSENT
Component qualifier not present.
ERROR_INVALID_PARAMETER
An invalid parameter was passed to the function.
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.
Any Action Error
An error relating to an action occurred.
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.

QuickInfo

Windows NT: Requires version 4.0 or later. Available as a redistributable for Windows NT 4.0.
Windows: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Windows CE: Unsupported.
Header: Declared in msi.h.
Import Library: Use msi.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT.

See Also

Component-Specific Functions


MsiQueryFeatureState

The MsiQueryFeatureState function returns the installed state for a product feature.

INSTALLSTATE MsiQueryFeatureState(
  LPCTSTR szProduct,    // product code
  LPCTSTR szFeature     // feature ID
);

Parameters

szProduct
Specifies the product code for the product that contains the feature of interest.
szFeature
Identifies the feature of interest.

Return Values

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.

QuickInfo

Windows NT: Requires version 4.0 or later. Available as a redistributable for Windows NT 4.0.
Windows: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Windows CE: Unsupported.
Header: Declared in msi.h.
Import Library: Use msi.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT.

See Also

System Status Functions


MsiQueryProductState

The MsiQueryProductState function returns the installed state for a product.

INSTALLSTATE MsiQueryProductState(
  LPCTSTR szProduct  // product code
);

Parameters

szProduct
Specifies the product code that identifies the product to be queried.

Return Values

INSTALLSTATE_ABSENT
The product is not installed.
INSTALLSTATE_BAD_CONFIGURATION
The configuration data is corrupt.
INSTALLSTATE_DEFAULT
The product is installed.
INSTALLSTATE_INVALIDARG
An invalid parameter was passed to the function.
INSTALLSTATE_UNKNOWN
The product code does not identify a known product.

QuickInfo

Windows NT: Requires version 4.0 or later. Available as a redistributable for Windows NT 4.0.
Windows: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Windows CE: Unsupported.
Header: Declared in msi.h.
Import Library: Use msi.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT.

See Also

System Status Functions


MsiReinstallFeature

The MsiReinstallFeature function validates or corrects problems with features.

UINT MsiReinstallFeature(
  LPCTSTR szProduct,       // product code
  LPCTSTR szFeature,       // feature ID
  LPCTSTR dwReinstallMode  // one or more REINSTALLMODE modes
);

Parameters

szProduct
Specifies the product code for the product containing the feature to be reinstalled.
szFeature
Identifies the feature to be reinstalled.
dwReinstallMode
Specifies what to install. This parameter can be one or more of the following values.
Value | Meaning
REINSTALLMODE_REPAIR | Repair any defects encountered.
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.
REINSTALLMODE_FILEREPLACE | Reinstall all files regardless of version.
REINSTALLMODE_USERDATA | Insure required user regular entries.
REINSTALLMODE_MACHINEDATA | Insure required machine regular entries.
REINSTALLMODE_SHORTCUT | Validate shortcuts and progman items.

Return Values

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.

Remarks

The MsiReinstallFeature function can also verify registry entries and shortcuts.

QuickInfo

Windows NT: Requires version 4.0 or later. Available as a redistributable for Windows NT 4.0.
Windows: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Windows CE: Unsupported.
Header: Declared in msi.h.
Import Library: Use msi.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT.

See Also

Installation and Configuration Functions


MsiReinstallProduct

The MsiReinstallProduct function validates or corrects installation problems in products.

INSTALLSTATE MsiReinstallProduct(
  LPCTSTR szProduct,        // product code
  DWORD dwReinstallMode     // one or more REINSTALLMODE modes
);

Parameters

szProduct
Specifies the product code for the product to be reinstalled.
dwReinstallMode
Specifies the reinstall mode. This parameter can be one or more of the following values.
Value | Meaning
REINSTALLMODE_REPAIR | Repair any defects encountered.
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.
REINSTALLMODE_FILEREPLACE | Reinstall all the files regardless of version.
REINSTALLMODE_USERDATA | Insure required user regular entries.
REINSTALLMODE_MACHINEDATA | Insure required machine regular entries.
REINSTALLMODE_SHORTCUT | Validate shortcuts and progman items.

Return Values

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.

Remarks

The MsiReinstallProduct function typically validates or corrects installations.

QuickInfo

Windows NT: Requires version 4.0 or later. Available as a redistributable for Windows NT 4.0.
Windows: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Windows CE: Unsupported.
Header: Declared in msi.h.
Import Library: Use msi.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT.

See Also

Installation and Configuration Functions


MsiSetExternalUI

The MsiSetExternalUI function enables an external user-interface handler. This user interface is then used for all subsequent calls to user-interface-generating installer functions in this process.

INSTALLUI_HANDLER MsiSetExternalUI(
  INSTALLUI_HANDLER puiHandler, // UI handler
  DWORD dwMessageFilter,        // bit flags designating which messages to handle
  LPVOID pvContext              // application context
);

Parameters

puiHandler
Specifies a callback function that conforms to the INSTALLUI_HANDLER specification.
dwMessageFilter
Specifies which messages to handle.
pvContext
Pointer to an application context. This context is returned to the application through the user-interface handler.

Return Values

The return value is the previously set external handler, or 0 if there was no previously set handler.

QuickInfo

Windows NT: Requires version 4.0 or later. Available as a redistributable for Windows NT 4.0.
Windows: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Windows CE: Unsupported.
Header: Declared in msi.h.
Import Library: Use msi.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT.

See Also

Interface and Logging Functions


MsiSetInternalUI

The MsiSetInternalUI function enables the installer's internal user interface. This user interface is then used for all subsequent calls to user-interface-generating installer functions in this process.

INSTALLUILEVEL MsiSetInternalUI(
  INSTALLUILEVEL dwUILevel,  // UI level
  HWND *phWnd                // handle of owner window
);

Parameters

dwUILevel
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_NOCHANGE | The installation level is not changed.
INSTALLUILEVEL_NONE | Completely silent installation.

phWnd
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).

QuickInfo

Windows NT: Requires version 4.0 or later. Available as a redistributable for Windows NT 4.0.
Windows: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Windows CE: Unsupported.
Header: Declared in msi.h.
Import Library: Use msi.lib.

See Also

Interface and Logging Functions


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
Specifies the product code for the product that owns the feature to be used.
szFeature
Identifies the feature to be used.

Return Values

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 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.

QuickInfo

Windows NT: Requires version 4.0 or later. Available as a redistributable for Windows NT 4.0.
Windows: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Windows CE: Unsupported.
Header: Declared in msi.h.
Import Library: Use msi.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT.

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
Specifies the path and file name of the package.

Return Values

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.

QuickInfo

Windows NT: Requires version 4.0 or later. Available as a redistributable for Windows NT 4.0.
Windows: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Windows CE: Unsupported.
Header: Declared in msi.h.
Import Library: Use msi.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT.


Initialization Errors

Error Code | Error
ERROR_SUCCESS | initialization complete
ERROR_ALREADY_INITIALIZED | this engine object 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_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 | digital signature rejected


Action Errors

Error Code | Error
ERROR_INVALID_PARAMETER | One of the parameters was invalid
ERROR_SUCCESS | Action completed successfully
ERROR_UNKNOWN_PRODUCT | Product code is unrecognized
ERROR_INSTALL_FAILURE | Install failed
ERROR_BAD_CONFIGURATION | Corrupt configuration information
ERROR_INSTALL_SOURCE_ABSENT | The source was unavailable
ERROR_INSTALL_SUSPEND | The install was suspended
ERROR_INSTALL_USEREXIT | The user exited the install


INSTALLUI_HANDLER

The INSTALLUI_HANDLER function prototype defines a callback function that the Installer Service calls for progress notification and error messages.

INT(WINAPI*INSTALLUI_HANDLER)(
  LPVOID pvContext,   // application context
  UINT iMessageType,  // message type
  LPCTSTR szMessage   // message
);

Parameters

pvContext
Enables the application to determine its context when it is called back.
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_OUTOFMEMORY | Out-of-memory message
INSTALLMESSAGE_ERROR | Formatted error message
INSTALLMESSAGE_WARNING | Formatted warning message
INSTALLMESSAGE_USER | User request message.
INSTALLMESSAGE_INFO | Informative message for log
INSTALLMESSAGE_DIAGNOSTIC | Debug notification. This message displays if there is no log.
INSTALLMESSAGE_COMMONDATA Dialog information for UI. Type of data is specified in the first field, parameters follow in remaining fields. Fields are separated by colons. Types of COMMONDATA messages are:

1:LanguageID

2:Dialog Caption

3:Boolean, 1 to show cancel button, 0 to hide
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_ACTIONDONE | End of action sequence. Indicates an exit-modeless dialog box.

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


Roadmap to Installer Database Documentation

The Microsoftâ Windows® installer database documentation contains overview and reference material for developers who want to write tools that create or modify installer packages. Complete installer packages are then adopted by application developers as means to manage the installation of their applications. Some of the general information in this section is also useful for application developers and administrators who want to modify existing installer packages and installation processes by using custom actions. To help you find the information you need, the following list shows the main sections in the installer database documentation:

  • Installer Database Schema
  • Database Access
  • User Interface
  • Standard Actions
  • Properties
  • Summary Information Stream
  • Automation Interface
  • Glossary
  • Appendix


Installer Database Schema

The material in this section is primarily for developers who want to write tools that create new installer packages and who therefore 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. Some 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 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, will 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 installer database consists of many inter-related tables that together comprise a relational database of the information necessary to install a group of applications. Because the database is relational, changes made to one table get propagated automatically throughout the database. This is a very efficient process for introducing consistent changes into the installation process and means that users can more easily customize a large application or group of applications. The database tables therefore 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. It is helpful for understanding the scheme of the installer database to break it up into groups of related tables. The following sections describe groups of related 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 Installation Database Tables.


Core Tables Group

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. Assigning and publishing are the two types of feature advertisement.


File Tables Group

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. Every file belongs to one and only one component and no component belongs to more than one directory of the same level; therefore, because the File table and Directory table have an external key into the Component table, the database contains the entire structure of the installation. This fact become important when searching for applications.

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 Font table lists font files to be registered with the system.
  • The Resource table lists resource data files to be inserted into executables or DLLs.
  • 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 The IniFile table lists the .ini files and the information that the application needs to set in the file.


Registry Tables Group

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. For example, making registry entries into specific tables maximizes the benefits to the application from advertising applications and features.

The figure shows the registry entry group of tables and 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 Registry table holds the information that the application needs to put into the system registry.
  • The Extension table contains all of the extensions your application uses along with the features and components associated with the extensions.
  • The Verb table associates command-verb information with the file extensions listed in the Extension table. This results in an indirect link between the Verb and Features table that is needed for feature advertisement.
  • The TypeLib table provides information that needs to be placed in the registry for the advertisement and registration of type libraries.
  • The MIME table associates a MIME context type with a CLSID or a file extension. This results in 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 Icon table provides icon information which is copied to a file as a part of product advertisement.
  • 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.


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 every column in the installation database. Query this table to find out if a given column exists.
  • 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.
  • The _Sequence Table is used during the database validation process to ensure that all sequenced actions are in the correct order. The _Sequence table lists all the sequencing restrictions of all actions used in the installer database.
  • The _InstallValidate Table is used with the _Sequence table during the validation process to ensure that the actions occur in the correct order.
  • The _Required Table tracks the number of primary keys for all the tables in the database. It is only used during the database validation process.


Locator Tables Group

The Locator Tables Group of tables are 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 make sure 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 tasked 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.

  • The InstallUISequence table
  • The InstallExecuteSequence table
  • The AdminUISequence table
  • The AdminExecuteSequence table
  • The AdvtUISequence table
  • The 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.

Developers of installer packages will populate the Upgrade Table to create an installer package that upgrades an existing product.

  • The Upgrade table contains information on how the installer should perform an upgrade of a product and how to handle installations when related versions of the product are already installed.

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:

  • The InstallUISequence table
  • The InstallExecuteSequence table
  • The AdminUISequence table
  • The AdminExecuteSequence table
  • The AdvtUISequence table
  • The AdvtExecuteSequence table

The following topics describe how to use these tables:

  • Using the Directory Table
  • Using a Sequence Table


Using the Directory Table

The Directory table indicates the layout of your application. 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. For example, consider this 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


Using a Sequence Table

The authoring of the sequence tables is an essential part of developing an installer package because these tables specify the flow of the installation process. Sequence tables are the only place in an installer package where the flow can be specified. The flow is always linear and there can be no branching or looping.

There are six sequence tables in the installer database:

  • The InstallUISequence table
  • The InstallExecuteSequence table
  • The AdminUISequence table
  • The AdminExecuteSequence table
  • The AdvtUISequence table
  • The AdvtExecuteSequence table

Upon the execution of one of the top-level actions, INSTALL, ADVERTISE, and ADMIN, the installer begins advancing through the sequence of actions listed in one of the user interface, execution, or advertise sequence tables. The installer contains internal logic that determines which of the sequence tables to use.

  • The user interface (UI) sequence tables contain the exit dialogs and actions coming before the InstallValidate action. Actions from InstallValidate to the end of the install sequence are located in the execution sequence tables. The actions needed to advertise products and features are located in the advertise sequence tables.
  • A typical UI sequence table will begin with costing initialization actions, then the user interface actions, and then the ExecuteAction action, which starts the execution of the installation. Here is an example of a sequence table.
Action | Condition | Sequence
LaunchConditions |  | 10
AppSearch |  | 30
CCPSearch | CCP_TEST | 40
CCPDialog | NOT_CCP_SUCCESS | 50
MyCustomConfig | NOT Installed | 80
CostInitialize |  | 90
FileCost |  | 100
CostFinalize |  | 110
InstallDialog | NOT Installed | 120
MaintenanceDialog | Installed AND NOT Resume | 130
ActionDialog |  | 150
RegisterProduct |  | 170
InstallValidate |  | 210
InstallFiles |  | 330
MyCustomAction | $MyComponent > 2 | 440
InstallFinalize |  | 510

The sequence tables have three columns: Action, Condition, and Sequence. The Action column names the standard or custom action, or user interface wizard, the installer will execute. The Sequence column indicates the place of the record in the sequence and each record in the sequence table is sampled in order. The Condition column is a logical expression that causes the action to be executed if the expression is True and skipped if the expression is False. Conditions can be thought of as jumps and so the linear flow may not execute every action.

The following actions in this sequence table are defined by the installer and are therefore 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 therefore examples of custom actions and must be listed in the CustomAction table.

MyCustomConfig
MyCustomAction

The remaining entries in the Action field are dialogs. They therefore must be entries into the Dialog table.

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 will therefore 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.

For more examples of properties see Using Properties and for more information on how expressions are evaluated see MsiEvaluateCondition.


Installer Database Reference

Installation Database Reference

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 on the installer, see About Windows Installer.


Installation Database Tables

Following is a list of the Microsoft® Windows® installer database tables:

  • ActionText Table
  • AdminExecuteSequence Table
  • AdminUISequence Table
  • AdvtExecuteSequence Table
  • AdvtUISequence Table
  • AppSearch Table
  • BBControl Table
  • Billboard Table
  • Binary Table
  • BindImage Table
  • CCPSearch Table
  • CheckBox Table
  • Class Table
  • ComboBox Table
  • CompLocator Table
  • Component Table
  • Condition Table
  • Control Table
  • ControlCondition Table
  • ControlEvent Table
  • CreateFolder Table
  • CustomAction Table
  • Dialog Table
  • Directory Table
  • DrLocator Table
  • DuplicateFile table
  • Environment table
  • Error Table
  • EventMapping Table
  • Extension Table
  • Feature Table
  • FeatureComponents Table
  • File Table
  • Font Table
  • Icon Table
  • IniFile Table
  • IniLocator Table
  • InstallExecuteSequence Table
  • InstallUISequence Table
  • LaunchCondition Table
  • ListBox Table
  • ListView Table
  • Media Table
  • MIME Table
  • MoveFile Table
  • ODBCAttribute Table
  • ODBCDataSource Table
  • ODBCDriver Table
  • ODBCSourceAttribute Table
  • ODBCTranslator Table
  • Patch Table
  • PatchPackage Table
  • ProgId Table
  • Property Table
  • PublishComponent Table
  • RadioButton Table
  • Registry Table
  • RegLocator Table
  • RemoveFile Table
  • RemoveIniFile Table
  • RemoveRegistry Table
  • ReserveCost Table
  • Resource Table
  • SelfReg Table
  • ServiceControl Table
  • ServiceInstall Table
  • Shortcut Table
  • Signature Table
  • TextStyle Table
  • TypeLib Table
  • UIText Table
  • Upgrade Table
  • Verb Table
  • _Validation Table
  • _Columns Table
  • _InstallValidate Table
  • _Required Table
  • _Sequence Table
  • _Tables Table


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
  • KeyFormatted
  • Template
  • Condition
  • GUID
  • Version
  • Language
  • Binary
  • CustomSource
  • Cabinet
  • Shortcut

Text

The Text data type is a text string. No validation is done on this string.

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 letters, 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. To include a long 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 pipe 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.

During validation, "*" is treated as representing two or more characters. For example, "weather*.txt" would not pass validation because it does not fit into the eight-character name, period (.), and 3-character extension filename format. However, "weather?.txt" would pass validation.

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, are replaced in the string by the value of the property. 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 subpath.

Examples:

  • \\server\share\temp
  • c:\temp
  • \temp

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.

    If no properties are found, all the text in the braces, including the braces themselves, is removed.

KeyFormatted

The KeyFormatted data type is a text string, identical to Formatted, except with the following additional keys:

  • 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.
  • 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 state of the Action column in the Component table affects the install directory used to replace the substring. If the component is selected to be installed locally, the target directory is used. If the component is selected to run from source, the source directory is used. If the component is not selected or missing, the substring is removed.

Multiple instances of KeyFormatted properties are allowed and the KeyFormatted properties can be embedded within a string.

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.

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.

Version

The Version data type is a text string containing a valid version string. A version string has the format

xx.xx.xxxx.xxxx

where x is a digit. Version is only used in the File table. If a file has a version, it must also have a language associated with it. If the language is neutral, specify 0 (zero) in the Language column of the File table.

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.

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. Although, as an external key into the Property table, it isn't evaluated because properties can be added at run-time.

Cabinet

The Cabinet data type is usually used in the Cabinet column of the Media table. If the cabinet name is preceded by the pound sign (#), the characters following it are interpreted as a Filename. The (#) is used to denote a cabinet located in a stream inside the database.

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 KeyFormatted 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 and written to the log for actions that take a noticeably 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 or written to the log when the action is executing.
Template
Optional localized format template used to format action data records for display during action execution. If no template is supplied, the action data is not displayed.

Remarks

The entries in the ActionText table typically refer to actions in sequence tables. However, there are other "pseudo-actions" performed by the installer that are not listed in the sequence table but still require text to be specified in this table. These required entries are listed below. The action name and template must be authored exactly as given, 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 Admin actions that are executed when the top-level ADMIN action is executed. The columns and Special Terminate Actions definitions are identical to those of the InstallExecuteSequence table.

ADMIN actions in the install sequence up to the InstallValidate action, and any exit dialogs, 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 has any necessary initialization actions such as LaunchConditions, CostInitialize, FileCost, and CostFinalize.

The AdminExecuteSequence table has the following columns.

Column | Type | Key | Nullable
Action | Identifier | Y | N
Condition | Condition |  | Y
Sequence | Integer |  | Y

Columns

Action
Name of the action to execute, either a standard action, 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 conditional syntax, see MsiEvaluateCondition.
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 never to be executed. The following negative values indicate that this action is to be executed if the Action Sequencer returns the associated return code.
This value | Corresponds with this return code
-1 | Successful completion (iesSuccess).
-2 | User terminates install (iesUserExit).
-3 | Fatal exit terminates (iesFailure).
-4 | Install is suspended (iesSuspend).

Zero, all other negative numbers, or a Null value indicate that the action is never to be executed.


AdminUISequence Table

The AdminUISequence table lists ADMIN actions that are executed when the top-level ADMIN action is executed. The columns and Special Terminate Actions definitions are identical to those of the InstallUISequence table.

ADMIN actions in the install sequence up to the InstallValidate action, and any exit dialogs, 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 has any necessary initialization actions such as LaunchConditions, CostInitialize, FileCost, and CostFinalize, and it has the ExecuteAction action.

The AdminUISequence table has the following columns.

Column | Type | Key | Nullable
Action | Identifier | Y | N
Condition | Condition |  | Y
Sequence | Integer |  | Y

Columns

Action
Name of the action to execute, either a standard action, 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 conditional syntax, see MsiEvaluateCondition.
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 never to be executed. The following negative values indicate that this action is to be executed if the Action Sequencer returns the associated return code.
This value | Corresponds with this return code
-1 | Successful completion (iesSuccess).
-2 | User terminates install (iesUserExit).
-3 | Fatal exit terminates (iesFailure).
-4 | Install is suspended (iesSuspend).

Zero, all other negative numbers, or a Null value indicate that the action is never to be executed.


AdvtExecuteSequence Table

The AdvtExecuteSequence table lists advertise actions the installer executes when the top-level ADVERTISE action is executed. The columns and Special Terminate Actions definitions are identical to those of the InstallExecuteSequence table.

Advertise actions in the sequence up to the InstallValidate action, and any exit dialogs, are located in the AdvtUISequence table. All actions from the InstallValidate action through the end of the install sequence are in the AdvExecuteSequence table.

The AdvtExecuteSequence table has the following columns.

Column | Type | Key | Nullable
Action | Identifier | Y | N
Condition | Condition |  | Y
Sequence | Integer |  | Y

Columns

Action
Name of the action to execute, either a built-in action, a custom action, or a user interface wizard.

Primary table key.

Condition
Logical expression. If the expression evaluates to expFalse, the action is skipped. If the expression syntax is invalid, the sequence terminates, returning iesBadActionData. For information on the conditional syntax, see MsiEvaluateCondition.
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 never to be executed. The following negative values indicate that this action is to be executed if the installer returns the associated return code.
This value | Corresponds with this return code
-1 | Successful completion (iesSuccess).
-2 | User terminates install (iesUserExit).
-3 | Fatal exit terminates (iesFailure).
-4 | Install is suspended (iesSuspend).

Zero, all other negative numbers, or a Null value indicate that the action is never to be executed.

The actions that may be in the AdvtExecuteSequence table are:


AdvtUISequence Table

The AdvtUISequence table lists advertise actions the installer executes when the top-level ADVERTISE action is called. The columns and Special Terminate Actions definitions are identical to those of the InstallExecuteSequence table.

Advertise actions in the sequence up to the InstallValidate action, and any exit dialogs, are located in the AdvtUISequence table. Advertise actions from the InstallValidate action through the end of the sequence are in the AdvtExecuteSequence table.

The AdvtUISequence table has the following columns.

Column | Type | Key | Nullable
Action | Identifier | Y | N
Condition | Condition |  | Y
Sequence | Integer |  | Y

Columns

Action
Name of the action to execute, either a built-in action, a custom action, or a user interface wizard.

Primary table key.

Condition
Logical expression. If the expression evaluates to expFalse, the action is skipped. If the expression syntax is invalid, the sequence terminates, returning iesBadActionData. For information on the conditional syntax, see MsiEvaluateCondition.
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 never to be executed. The following negative values indicate that this action is to be executed if the installer returns the associated return code.
This value | Corresponds with this return code
-1 | Successful completion (iesSuccess).
-2 | User terminates install (iesUserExit).
-3 | Fatal exit terminates (iesFailure).
-4 | Install is suspended (iesSuspend).

Zero, all other negative numbers, or a Null value indicate that the action is never to be executed.

The actions that may be in the AdvtUISequence table are:


AppSearch Table

The AppSearch table contains the properties that must be set to the search result of a corresponding file signature.

The AppSearch table has the following columns.

Column | Type | Key | Nullable
Property | Identifier | Y | N
Signature_ | Identifier | Y | N

Columns

Property
When the AppSearch action is run, this property is set to the location of the file indicated by the Signature_ column.
Signature_
The Signature_ represents a unique file signature and is also the external key into the Signature table, RegLocator table, IniLocator table, CompLocator table, and DrLocator table.

Remarks

This table is used by the AppSearch action.


BBControl Table

The BBControl table contains the controls to be displayed on the specified 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. Combined with the Billboard_ column, they form the primary key to this table.
Type
The type of the control. For a list of supported control types, see Control Overview. It is not advisable to put any control other than the static ones (that is, text, bitmap, icon) on a billboard. The author can also specify a custom control type.
X
Horizontal coordinate of the upper-left corner of the bounding rectangle of the control.

Non-negative numbers only.

Y
Vertical coordinate of the upper-left corner of the bounding rectangle of the control.

Non-negative numbers only.

Width
Width of the bounding rectangle of the control.

Non-negative numbers only.

Height
Height of the bounding rectangle of the control.

Non-negative numbers only.

Attributes
A 32-bit word that specifies the attribute flags to be applied to this control. For a list of supported control attributes, see Control Overview.

Non-negative numbers only.

Text
A string used to set the initial text contained within a control (if appropriate). If the text is too long to be displayed on the control, the string is truncated. This column may be left blank. If the control is a pushbutton or a checkbox that contains a picture (icon or bitmap), this column is the name of the picture (a key into the Binary table). It is not possible to show both a picture and text on the same button.

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 system font. Coordinates for the controls are relative to the billboard.


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 into the Feature table. The billboard is shown only if this feature is being installed.

External key to column one of the Feature table.

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, they are displayed in the order defined by this column.

Non-negative numbers only.


Binary Table

The Binary table holds the binary data for items such as bitmaps, animations, and icons. The binary table is also typically used to store data for custom actions.

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 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_
The index into the File table. This must be an executable file.

External key to column one of the File table.

Path
A list of paths, separated by semicolons, that represent the paths to be searched to find the import DLLs. The list is usually a list of properties, each enclosed within 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, at least one of which needs to be present on a user's computer for the Compliance Checking Program (CCP).

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 table, RegLocator table, IniLocator table, CompLocator table, and DrLocator table.

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 checkboxes.

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 checkbox is turned on, the corresponding property is set to the described value. If there is no value specified or this table does not exist, the property is set to its original value when the checkbox is turned on. If the original value is Null, the property is set to "1".

Formatting

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
ProgId_Default | Text |  | Y
Description | Text |  | Y
Insertable | Integer |  | Y
AppId | GUID |  | Y
FileTypeMask | Text |  | Y
Icon_ | Identifier |  | Y
IconIndex | Integer |  | Y
DefInprocHandler | Filename |  | Y
Argument | KeyFormatted |  | Y
Feature_ | Identifier |  | N
Component_ | Identifier |  | N

Columns

CLSID
The Class identifier (ID) of a COM server.
Context
The server context for this server.

May be one of the following values:

LocalServer

LocalServer32

InprocServer

InprocServer32

ProgId
The default Program ID associated with this Class ID.
Description
Localized description associated with the Class ID and Program ID.
Insertable
Writes the Insertable key if it is non-zero and non-null.

Non-negative numbers only.

AppId
Application ID containing DCOM information for the associated application (string GUID). Not used in installer version 1.0.
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...

Icon_
External key into the Icon table specifying the icon file associated with this CLSID. Is written under the DefaultIcon key associated with the ProgId.

External key to column one of the Icon table .

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.
Feature_
External key into the Feature table specifying the feature that provides the COM server.

External key to column one of the Feature table.

Component_
External key into the Component table specifying the component whose key file provides the COM server.

External key to column one of the Component table.

Remarks

This table is referred to when the RegisterClassInfo action or the UnregisterClassInfo action is executed.


ComboBox Table

The lines of a combobox are not treated as individual controls; they are part of some combobox that functions as a control. This table lists the values for all comboboxes.

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 combobox.
Order
A positive integer used to determine the ordering of the items that appear in a single combobox list. The integers do not have to be consecutive. If a combobox is defined as ordered, all the items should have an Order value. If the combobox is defined as unordered, this column is ignored.

Positive numbers only.

Value
The value string associated with this item. Selecting this line of the combobox sets the associated property (specified in Property) to this value.
Text
The 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

Formatting

The contents of the Value and Text fields are formatted by the MsiFormatRecord function when the control is created, so 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.
This value | Indicates that the key path represents a
0 | directory
1 | file name

If this column is absent, the value is assumed to be one (file name).

Remarks

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.


Component Table

The Component table lists components.

The Component table 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.

Table key.

Directory_
External key of an entry in the Directory table. This is a property name whose value contains the actual path, set either by the AppSearch action or with the default setting obtained from the Directory table.

External key to column one of the Directory table.

Attributes
Remote execution option.

The first two bits indicate whether the component can be run from source. The following table lists valid values.
This value | Indicates that the item
0 (irsLocalOnly) | Cannot be run from the source.
1 (irsSourceOnly) | Can run only from the source.
2 (irsOptional) | Can run either locally or from the source.

The rest of the significant bits are bit flags.

The 3rd bit is the irsRegistryKeyPath bit.

If the third bit is set, the KeyPath column, if not Null, is interpreted as a key into the Registry table. If this bit is not set, the KeyPath column, if not Null, is interpreted as a key into the File table.

The 4th bit is the icaSharedDllRefCount bit. If the 4th bit is set, the installer will always increment the reference count in the shared DLL registry. If the 4th bit is not set, then the installer will only increment the reference count if it already exists.

The 5th bit is the icaPermanent bit. If the 5th bit is set then the component will not be removed on uninstall.

Condition
A conditional statement that indicates if a component should be installed. If the condition is Null or evaluates to True, the component is enabled. If the condition evaluates to False, the component is disabled. If a component is disabled, it will not be installed regardless of the Action state associated with the component. For information on the conditional expression syntax, see the MsiEvaluateCondition function.
KeyPath
This value points to the component member that will be used for detection. It is also the path that is returned by the MsiGetComponentPath function. If not Null, KeyPath is either the primary key into the File table or the Registry table based on the irsRegistryKeyPath bit in the Attributes column. In both cases, the entity (file or folder) should belong to this component. If Null, the folder of the Component (Component.Directory_) is used as the key path. Two components can not share the same key path value.

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, then the installer will always increment the count when it is installing the file and decrement it when it is uninstalling. However, if the icaSharedDllRefCount bit is not set and the reference count does not already exist, the installer will not create one.

If the icaSharedDllRefCount bit is not set, another application could 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 icaSharedDllRefCount 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 the icaSharedDllRefCount bit.


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 to a Feature entry in the Feature table.

External key into column one of the Feature table.

Level
New selection Level to set in the Feature table if Condition evaluates to TRUE.
Condition
If this conditional expression evaluates to TRUE, the Level value in the Feature entry of the Feature table is set to the Level value in this table. For information on the conditional syntax, see MsiEvaluateCondition.

Remarks

If Condition evaluates to True, the corresponding Level value in the Feature table is set to the value specified in the Condition table Level column.

Using this mechanism, any feature can be permanently disabled (by setting the Level to 0), set to be always installed (by setting the Level to 1), or set to a different install priority (by setting Level to an intermediate value). 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.

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 Dialog table, the name of the dialog.

External key to column one of the Dialog table.

Control
Name of the control. This name must be unique within a dialog but can be repeated on different dialogs. Combined with the Dialog_ column, they form the primary key to this table.
Type
The type of the control. For a list of supported control types, see Control Overview. The author can specify a custom control type.
X
Horizontal coordinate of the upper-left corner of the bounding rectangle of the control.

Non-negative numbers only.

Y
Vertical coordinate of the upper-left corner of the bounding rectangle of the control.

Non-negative numbers only.

Width
Width of the bounding rectangle of the control.

Non-negative numbers only.

Height
Height of the bounding rectangle of the control.

Non-negative numbers only.

Attributes
A 32-bit word that specifies the stylebit flags to be applied to this control. For a list of supported control stylebits, see Control Stylebits List.

Non-negative numbers only.

Property
The name of a defined property to be linked to this control. Radio button, listbox, and combobox values are tied into a group by being linked to the same property. This column is required for all active controls and is ignored for others.
Text
A string used to set the initial text contained within a control (if appropriate). If the text is too long to be displayed on the control, the string is truncated. The text string may be blank. This text can contain embedded properties. For the syntax of this string, see the MsiFormatRecord function. For the VolumeCostList control, the ListView control, the DirectoryList control, and the SelectionTree control, you can enter short descriptive text. This text will never be seen by the user, but will be read by the screen readers as the description of the given control. This field can also contain other special information specific to the given control type. For details, see the documentation for the specific control type.
Control_Next
The name of another control on the same dialog. The tab order of the controls on the dialog follow this link, and the links must form one cycle. Some controls (for example, static text) can be left out of the cycles completely, in which case this entry may be left blank.

External key to column two of the Control table.

Help
The Help strings used with the button. The text is optional. The string is divided into two parts, divided by a separator 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. 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 system font. Coordinates for the controls are relative to the billboard.


ControlCondition Table

The ControlCondition table allows the author to specify special actions to be applied to controls based on the value of a property. 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 that, combined with the Control_ key, uniquely identifies a control.

External key to column one of the Dialog table.

Control_
An external key that, combined with the Dialog_ key, uniquely identifies a control.

External key to column two of the Control table.

Action
The desired action to be taken on the specified 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 standard 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 conditional syntax, see MsiEvaluateCondition.


ControlEvent Table

The ControlEvent table allows the author to specify exactly what should happen when the user interacts with any control within a dialog. For example, a click of a pushbutton can be defined to trigger a transition to another dialog, to exit a dialog 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 that, combined with the Control_ key, uniquely identifies a control.

External key to column one of the Dialog table.

Control_
An external key that, combined with the Dialog_ key, uniquely identifies a control.

External key to column two of the Control table.

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_. Any control type can register as a publisher or subscriber of some event. For a list of possible values, see Control Overview. To set a property, put [Property_Name] in this field and the new value in the argument field ({ } for Null).
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. The argument of the Install action is a number defining the install level, and so forth.
Condition
A standard conditional statement that specifies under which conditions an event should be triggered. If this statement does not evaluate to TRUE, the event does not take place. May be left blank.
Ordering
An integer used to order several events tied to the same control. May be left blank.

Non-negative numbers only.


CreateFolder Table

The CreateFolder table contains references to folders that need to be explicitly created for a component.

The CreateFolder table has the following columns.

Column | Type | Key | Nullable
Directory_ | Identifier | Y | N
Component_ | Identifier |  | N

Columns

Directory_
External key into the Directory table.

External key to column one of the Directory table.

Component_
External key into the Component table.

External key to column one of the Component table.

Remarks

These folders are created when the component is installed. An attempt is made to remove such folders only when the component is uninstalled or moved to run-from-source, not just when the folders become empty. Folders created by the installer but not listed in this table are removed whenever they become empty.

This table is referred to when the CreateFolders action or the RemoveFolders action is executed.


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 CustomAction table has the following columns.

Column | Type | Key | Nullable
Action | Identifier | Y | N
Type | Integer |  | N
Source | CustomSource |  | Y
Target | Text |  | Y

Columns

Action
Name of action. The action normally appears in a sequence table unless it is called by other custom actions. If the name matches any built-in action, the custom action is never called.

Primary table key.

Type
The numeric custom action type.

One of icvEnum, as described in Custom Action Types.

Source
External key into the table containing the source of the code.

External key, referencing column one of one of the following tables containing the source of the 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
Execution parameter.

The value depends on the type of custom action being performed.
Target contains this value | When performing this 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.


Dialog Table

The Dialog table contains all the dialogs that appear in the user interface in both 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, name of the dialog.
Hcentering
Horizontal position of the dialog on a 0-100 scale.

Range = 0 to 100 (0 is the left edge of the screen, 100 is the right edge).

Vcentering
Vertical position of the dialog on a 0-100 scale.

Range = 0 to 100. (0 is the top of the screen, 100 is the bottom).

Width
Width of the bounding rectangle of the dialog.

Non-negative numbers only.

Height
Height of the bounding rectangle of the dialog.

Non-negative numbers only.

Attributes
A 32-bit word that specifies the attribute flags to be applied to this dialog.

Non-negative numbers only. For a list of options, see Dialog Stylebits List.

Title
A text string specifying the title to be displayed in the title bar of the dialog window.
Control_First
An external key that, combined with the Dialog column, forms the primary key of the Control table. This defines the control that has the focus when the dialog is created. This column is ignored on the Error dialog.

External key to column two of the Control table.

For compatibility with screen readers, when authoring a dialog with an Edit, PathEdit, ListView, ComboBox or VolumeSelectCombo control as the first active control, you must make the text field belonging to the edit field the first active control in this column. Since static text can not take focus, when the dialog is created the edit field has the focus initially as intended — but doing this ensures that screen readers show the correct information.

Control_Default
An external key that, combined with the Dialog entry, forms the primary key of the Control table. This defines the default control (that is, hitting the Return key is equivalent to clicking this control). If this column is left blank, no default control is defined. This column is ignored on the Error dialog.

External key to column two of the Control table.

Control_Cancel
An external key that, combined with the Dialog entry, forms the primary key of the Control table. This defines the cancel control (that is, hitting the Esc key or clicking the Close icon on the dialog is equivalent to clicking this control). If this column is left blank, no cancel control is defined. This column is ignored on the Error dialog.

External key to column two of the Control table.

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 system font.

Wizard Dialogs

The two centering values are ignored for subsequent dialogs in a wizard sequence (that is, those created by a NewDialog ControlEvent). Subsequent dialogs display in the same position as the previous dialog, as defined by the author, or as positioned by the user.


Directory Table

The Directory table represents 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 an unique identifier for a directory or directory path. This column can contain the full path to a target directory or a property set to the full path of a target directory. If this column contains a property which is not set, then the target directory takes the name listed in the DefaultDir column and has the parent directory given in the Directory_Parent column.

If the Directory_Parent column is Null or equal to the value of the Directory column, then the Directory column represents a root target directory of the installation.

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. To resolve the full path of the parent directory, use the reference in the Directory_Parent column as 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 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 equal to the Directory column, then the DefaultDir column is the name of a root source directory.

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.

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. Every Directory table must have a root entry with a Directory column value equal to the TARGETDIR property.

During an ADMIN install the resulting admin image should resemble the source. To copy the admin image into the root directory named TARGETDIR, use the source directory names when resolving the target directories.

Directory resolution is performed during the CostFinalize action and is done as follows:

Root Destination Directories

Root directories entries are those with a Null Directory_Parent value or a Directory_Parent value identical to the Directory value. The value in the Directory column is interpreted as the name of a property defining the location of the destination directory. If the property is defined, the destination directory is resolved to the property's value. If the property is undefined, the ROOTDRIVE property is used instead to resolve the path.

Root Source Directories

The value of the DefaultDir column for root entries is interpreted as the name of a property defining the source location of this directory This property must be defined or an error occurs. This is typically 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.

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_ 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 DrLocator table.

External key to column one of the Signature table.

Parent
The parent directory signature. This is a key into one of the following tables: RegLocator table, the IniLocator table, the CompLocator table, or the DrLocator table. If it is Null and the Path column does not expand to a full path, all the fixed drives of the user system are searched using the Path.
Path
The path on the user system. This is a either a subpath below the value of the Parent or a full path. The path may contain properties enclosed within square brackets ([ ]) that are expanded.
Depth
The depth below the path to which the Signature_ is recursively searched. If absent, the depth is assumed to be zero.

Non-negative numbers only.

Remarks

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.


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
Primary key, non-localized token, used to uniquely identify a particular DuplicateFile record.
Component_
Foreign key referencing an entry in the Component table. If this component is not selected for installation or removal, no action is taken on the associated DuplicateFile entry.

External key to column one of the Component table.

File_
Foreign key referencing an entry in the File table representing the original file to be duplicated.
DestName
Name to be given to the duplicate file. If blank, the destination file is given the same name as the original file
DestFolder
Name of a property whose value is the full path 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 file, 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 | Filename |  | 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 name of the environment variable. The key values will be written or removed depending upon which of the characters in the following table are prefixed to the name.
Prefix Meaning
= The name/value is to be created when installed.
+ The name/value is to be created, if absent, when installed.
- The name/value is to be deleted, if present, when the component is uninstalled.
=- The value is set on install and removed on uninstall. This is the usual behavior.
=+ This is not a valid prefix
* The name refers to a system environment variable and by default the value will be written to the user's environment. This prefix is used with Windows NT.

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 value that is to be set as a formatted string. The contents of this field are modified as follows by using the character [~].

If [~] precedes the string, then the string will be attached at the end of the existing value.

If [~] follows the end of the string, then the string will be inserted at the beginning of the existing value.

If no [~] is present, then the string represents the entire value to be set or deleted.

If the Value field is blank, then the variable will be removed.

The character adjacent to the [~] in a preceding or appending value acts as a delimiter and separates one value from the next. For example, to add a value to the end of a semi-colon delimited list use "[~];new value".

Component_
External key to column one of the Component table. This column specifies the component whose key file provides the extension server.


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
The integer error number, obtained from header file IError(...) macros.

Non-negative numbers only.

Message
Error formatting template. This table is initially generated by the build process to contain the debug format templates.

The following table lists reserved messages.
Number | Description
0 (imsgInfo) | Header for log-only messages, for example, "Info [1]. "
1 (imsgWarning) | Header for warning messages, for example, "Warning [1]."
2 (imsgError) | Header for error messages, for example, "Error [1]."
3 (imsgNotice) | Header for notifications (log-only if log enabled), for example, "Notice [1]."
4 (imsgActionStart) | Format template for action start message, for example, "Action: [1]. [2]"
5 (imsgDebugError) | Format template for debug error code in final build.
6 (imsgDefaultError) | Default format template if the error is not in the Error table.
7 (imsgLogHeader) | Log header line (printf template for date/time).
8 (imsgLogTrailer) | Log trailer line (printf template for date/time).

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 that, combined with the Control_ key, uniquely identifies a control.

External key to column one of the Dialog table.

Control_
An external key that, combined with the Dialog_ key, uniquely identifies a control.

External key to column two of the Control table.

Event
An identifier that specifies the type of the event that the control subscribes to.
Attribute
The name of the control attribute that is set when this event is received. The argument of the event is passed as the argument of the Attribute call to change this attribute of the control. This column may be left blank if no attribute of the control should be changed by the publisher; in this case the publisher can still enable, disable, hide, or unhide the control.

Remarks

More than one control on a dialog can be specified as a subscriber to the same event.


Extension Table

The Extension table contains file extension servers information that must be generated as a part of the 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
ProgId_ | Text |  | Y
ShellNew | Text |  | Y
ShellNewValue | Text |  | Y
Feature_ | Identifier |  | N
Component_ | Identifier |  | N

Columns

Extension
The extension associated with the table row. The extension can be up to 255 characters.
ProgId_
Program ID associated with this extension. If present, the ShellNew key is created under this key — otherwise it is placed directly under the extension key. Foreign key into the ProgId table.
ShellNew
Subkey for the type of ShellNew Data: FileName, Command, Data, or NullFile.
ShellNewValue
Value written for ShellNew. May reference Feature/Component.
Feature_
External key into the Feature table specifying the feature that provides the extension server.

External key to column one of the Feature table.

Component_
External key into the Component table specifying the component whose key file provides the extension server.

External key to column one of the Component table.

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.

The Feature table 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.

Primary table key.

Feature_Parent
Optional key of a parent record in the same table. If the parent feature is not selected, this feature is not installed.

Key pointing to the Feature column of this table. Null indicates that this feature has no parent (root item). The Feature_Parent column must not equal the Feature column of the same record (that is, an item cannot be its own parent).

Title
Short text identifying a visible feature item.
Description
Longer descriptive text describing a visible feature item.
Display
Numeric sort order, used to specify 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, the record is not displayed. If the value is odd, the feature node is expanded initially. If the value is even, the feature node is collapsed initially.

Level
The install level at which the entry is initially selected. 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. The Browse button becomes when the column is non-null, and when the particular feature is selected in the user interface. The properties used in this column must be public and have an identifier consisting entirely of uppercase letters. This column is a key into the Directory table and any of the directories indicated to be configurable here will also belong to that table.
Attributes
Remote execution option.

The lowest two bits indicate the favored state of the feature. The following table lists valid values for these two bits.
This value | Means this feature will be installed
0 (ifrsFavorLocal) | Locally, if possible.
1 (ifrsFavorSource) | To run from the source, if possible.
2 (ifrsFavorParent) | Using the remote execution option of the parent feature. This is not allowed for parent features.

The rest of the significant bits are bit flags.

  • The 3rd bit is the ifrsFavorAdvertise bit.
  • The 4th bit is the ifrsDisallowAdvertise bit. The ifrsFavorAdvertise and the ifrsDisallowAdvertise bits cannot both be set for a particular feature.
  • The 5th bit is the ifrsUIDisallowAbsent bit.

These bits work together in the following manner.

  1. If the application has not already been installed by the installer and if no feature state request has been made via any of the following properties: ADDLOCAL, ADDSOURCE, ADDDEFAULT, COMPADDLOCAL, COMPADDSOURCE, FILEADDLOCAL, FILEADDSOURCE, REMOVE, REINSTALL, or ADVERTISE, then:
    • If the feature install level is greater than or equal to the current install level, or is 0, then the default state is NULL (i.e. no change).
    • Otherwise, if the ifrsFavorAdvertise bit is set, its default state is set to Advertise.
    • The lower 2 bits determine the default state.
  2. If a feature is to be installed to the authored default (the ADDDEFAULT property has the feature as part of its value list), the ifrsFavorAdvertise bit is always ignored. The state is determined by the lower 2 bits.
  3. If a feature is to be installed to the Advertise state via the ADVERTISE property, and if the ifrsDisallowAdvertise bit is not set, the state is set to Advertise. Otherwise, the state is determined by the lower 2 bits.
  4. If a feature is to be installed to the Advertise state and its parent must be installed, the Advertise state is preferred for the parent unless ifrsDisallowAdvertise bit is set for the parent — in which case the state (of the parent) is determined by the lower 2 bits.
  5. If a feature is to be installed to the Advertise state, the Advertise state for the children is preferred unless ifrsDisallowAdvertise bit is set for the child — in which case the state (of the child) is set to Absent.
  6. The Advertise state is relevant only to features and not to the components of the features. Hence feature state transitions to and from the Advertise state are to be treated as transitions to and from the Absent state for the constituent components.
  7. The user interface does not display the option to change to the Absent or the Advertise state if the corresponding ifrsUIDisallowAbsent bit or ifrsDisallowAdvertise bit is set for that feature.

If this column is left blank, the value defaults to zero (ifrsFavorLocal). For more information about Attributes options, see Attributes Column in the Remarks section that follows. For more information on how features are selected for installation, see FeatureRequestState property.

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.

Features and Components

A feature is a distinct subset of a product consisting of one or more components. Each component is defined in the Component table, and the link between a feature and its components is defined in the FeatureComponents table.

Any component can be shared between two or more features. If two or more features refer to the same component, that component is selected for installation if any of the associated features are selected. For more information about shared components, see the Attributes Column that follows.

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. Once the installation is initialized, the installer user interface could be authored to give the user the opportunity to modify the Install Level of any feature in the Feature table. For example, the author could define Install Level values that represent specific installation options, such as Complete, Typical, or Minimum, and then create a dialog that allows the user to select one of these states. Depending on the state the user selects, the dialog would set 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 containing a Selection Tree control. The Selection Tree would then allow the user to individually change whether each feature is installed.

Attributes Column

If a feature is marked as ifrsFavorLocal and this feature is to be installed, all components that are related to this feature (and are not marked for source install) are installed locally. Those components marked as irsSourceOnly in the Component table are still installed to run from the source CD/server. Similarly, the components of features marked ifrsFavorSource are installed to run from the source CD/server (unless marked to be installed locally). A component (not marked irsSourceOnly) that is shared among two or more features is installed locally if at least one of those features is marked ifrsFavorLocal, even if the other features are marked ifrsFavorSource.


FeatureComponents Table

The FeatureComponents table defines the relationship between features and components. Specifically, for each feature, this table lists all the components that make up a feature.

The FeatureComponents table has the following columns.

Column | Type | Key | Nullable
Feature_ | Identifier | Y | N
Component_ | Identifier | Y | N

Columns

Feature_
External key into the Feature table.

External key to column one of the Feature table.

Component_
External key into the Component table.

External key to column one of the Component table.

Remarks

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 the complete list of source files with their various attributes, ordered by a unique, non-localized identifier. Files can be stored on the source media either as individual files, or compressed within a cabinet file.

The File table has the following columns.

Column | Type | Key | Nullable
File | Identifier | Y | N
Component_ | Identifier |  | N
FileName | Filename |  | N
FileSize | DoubleInteger |  | Y
Version | Version |  | Y
Language | Language |  | Y
Attributes | Integer |  | Y
Sequence | Integer |  | N

Columns

File
A non-localized token that matches a file identifier in the cabinet. For uncompressed files, this field is ignored.
Component_
External key into the Component table that references the Component that controls the file.

External key to column one of the Component table.

FileName
File name used for installation. The name may be localized. This may be formatted as a short file name | long file name pair.
FileSize
Size of the file in bytes.

Non-negative value only.

Version
For versioned files, this is the version string. For non-versioned files, this is blank.

The Version field can also be set to contain the primary key of another record in the same table, producing a Companion File reference. In this case the version column is an external key to column one of the File table. See the remarks section for more information.

Language
List of decimal language IDs, separated by commas.
Attributes
Integer containing bit flags representing file attributes.

The following table shows the definition of the bit field.
Bit position | Decimal equivalent | Description
0 | 1 | Read-Only
1 | 2 | Hidden
2 | 4 | System
8 | 256 | Split - the file is split between two or more compression cabinets
9 | 512 | Vital - this file is vital for the proper operation of the component to which it belongs
10 | 1024 | ValidCheckSum
13 | 8192 | Uncompressed - the file is uncompressed on the source media

If the "Vital" 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 will appear with the options "Retry" or "Cancel". For a file that does not have the "Vital" bit 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 "ValidCheckSum" 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 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.

For uncompressed files, the File column is ignored, and the FileName column is used for both the source and destination file name. You must set the Uncompressed bit of the Attributes column for any file that is not compressed in a cabinet.

This table is referred to when the InstallFiles action, ProcessComponents action, FileCost action, RemoveFiles action, UpdateResources action, RegisterFonts action, or UnregisterFonts action is executed.

Companion Files

If the Version column contains the primary key of another record in the File table, a Companion File reference is produced with the referencing record termed the companion and the record being referred to termed the companion parent. In this situation, the installation state of the companion file is dependent not on its own file versioning information, but on that of its companion parent. For example, if a companion parent file is going to be installed over an existing, older version of the file, the companion file is also installed regardless of the version of an existing file (if any).

Only certain combinations of values in the Version column and the Language column are valid. The following table summarizes the possibilities.

Version | Language | Comment
1.2.3.4 | 1033 | Valid – version and language.
1.2.3.4 | (Null) | Invalid – version but no language.
1.2.3.4 | 0 | Valid – version and language are neutral.
Testdb | (Null) | Valid – companioned file but no language associated with it.
Testdb | 1033 | Valid – companioned file and language.
(Null) | 1033 | Valid – no version, but has a language associated with it (that is, typelib, helpfile).
Testdb | 1033 | Valid.


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 |  | N

Columns

File_
External key into the File table entry for the font file.
FontTitle
Font name.

Remarks

This table is referred to when the RegisterFonts action or the UnregisterFonts action is executed.


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.

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.


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
Directory_ | 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 name of the .ini file in which to write the information.
Directory_
External key into the Directory table indicating the directory in which the .ini file is located.

External key to column one of the Directory table.

Section
The .ini file section.
Key
The .ini file key within the section.
Value
The value to be written.
Action
The type of modification to be made.
This value | Indicates this action
0 | Creates or updates a .ini entry.
1 | Creates a .ini entry only if the entry does not already exist.
3 | Creates a new entry or appends a new comma-separated value to an existing entry.

Component_
External key into the Component table referencing the component that controls the installation of the .ini value.

External key to column one of the Component table.

Remarks

The .ini file information is written out when the corresponding component has been selected to be installed, either locally 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 find a file or directory using a .ini file. 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_
The Signature_ 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 IniLocator table.

External key to column one of the Signature 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, the entire line is read.

Non-negative numbers only.

Type
A Boolean value that determines if the .ini value read is a file name or a directory location.

If absent, Type is assumed to be 1, denoting a file name search.
Value | Meaning
0 | Directory
1 | File name

Remarks

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.

For an example of a sequence table, see Using a Sequence Table.


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 dialogs, 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 LaunchConditions, CostInitialize, FileCost, and CostFinalize.

The InstallExecuteSequence table has the following columns.

Column | Type | Key | Nullable
Action | Identifier | Y | N
Condition | Condition |  | Y
Sequence | Integer |  | Y

Columns

Action
Name of the action to execute, either a built-in action, a custom action, or a user interface wizard.

Primary table key.

Condition
Logical expression. If the expression evaluates to expFalse, the action is skipped. If the expression syntax is invalid, the sequence terminates, returning iesBadActionData. For information on the expression syntax, see MsiEvaluateCondition.
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 never to be executed. The following negative values indicate that this action is to be executed if the Action Sequencer returns the associated return code.
This value | Corresponds with this return code
-1 | Successful completion (iesSuccess).
-2 | User terminates install (iesUserExit).
-3 | Fatal exit terminates (iesFailure).
-4 | Install is suspended (iesSuspend).

Zero, all other negative numbers, or a Null value indicate that the action is never to be executed.

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.


InstallUISequence Table

The InstallUISequence 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 the exit dialogs, 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 LaunchConditions, CostInitialize, FileCost, and the CostFinalize, and it has the ExecuteAction action.

The InstallUISequence table has the following columns.

Column | Type | Key | Nullable
Action | Identifier | Y | N
Condition | Condition |  | Y
Sequence | Integer |  | Y

Columns

Action
Name of the action to execute, either a built-in action, a custom action, or a user interface wizard.

Primary table key.

Condition
Logical expression. If the expression evaluates to expFalse, the action is skipped. If the expression syntax is invalid, the sequence terminates, returning iesBadActionData. For information on the expression syntax, see MsiEvaluateCondition.
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 never to be executed. The following negative values indicate that this action is to be executed if the Action Sequencer returns the associated return code.
This value | Corresponds with this return code
-1 | Successful completion (iesSuccess).
-2 | User terminates install (iesUserExit).
-3 | Fatal exit terminates (iesFailure).
-4 | Install is suspended (iesSuspend).

Zero, all other negative numbers, or a Null value indicate that the action is never to be executed.

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.


_InstallValidate Table

The InstallValidate table is a system table used with the _Sequence table to ensure that the actions occur in the correct order, since some actions have pre- and post-conditional actions. This table is only used during the database validation process.

The InstallValidate table has the following columns.

Column | Type | Key | Nullable
Action | Identifier | Y | N
SectionFlag | Integer |  | N
Description | Text |  | Y

Columns

Action
Name of action.
SectionFlag
Section flag for location in the sequence table.
Description
Description of sections to which the action belongs.


LaunchCondition Table

The LaunchCondition table is used by the LaunchConditions action. It contains a list of conditions, all of which must be satisfied for the action to succeed.

The LaunchCondition table has the following columns.

Column | Type | Key | Nullable
Condition | Condition | Y | N
Description | Text |  | Y

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 listbox are not treated as individual controls, but they are part of a listbox that functions as a control. The ListBox table defines the values for all listboxes.

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 listbox.
Order
A positive integer used to determine the ordering of the items that appear in a single listbox. If the listbox is defined as ordered, all items should have an Order value. The integers do not have to be consecutive. If the listbox is defined as unordered, this column is ignored.

Positive numbers only.

Value
The value string associated with this item. Selecting the line sets the associated property to this value.
Text
The 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

Formatting

The contents of the Value and Text fields are formatted by the MsiFormatRecord function when the control is created, so 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, all the items should have an Ordering value. If the listview is defined as unordered, this column is ignored.

Positive numbers only.

Value
The value string associated with this item. Selecting the line sets the associated property to this value.
Text
The 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.
Binary_
The image data for the icon. This is a foreign key to the Binary table.

Remarks

Formatting

The contents of the Value and Text fields are formatted by the MsiFormatRecord function when the control is created, so 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.


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.

Non-negative numbers only. Minimum value is 1.

LastSequence
File sequence number for the last file for this media.

Non-negative numbers only.

DiskPrompt
Disk name, the visible text printed on the disk. This 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 in a cabinet. If cabinets are not being used, this column must be blank (or the entire column can be omitted).
VolumeLabel
The label attributed to the volume. This is the volume label returned by the GetVolumeInformation system API. If the SOURCEDIR property refers to a removable (floppy or CD-ROM) volume, this volume label is used to verify that the proper disk is in the drive before attempting to install files.
Source
The property defining the location of this cabinet file. If the Cabinet field is empty, this value is ignored. If this field is empty, the SOURCEDIR property is used.

Remarks

Sequence Numbers

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).

Cabinet Files

If the Cabinet name is preceded by an at symbol (@), the files referencing this Media table record are packed in a cabinet that is stored within a resource of the launching executable file.

Determining the SourceMode

The MSI Source Type 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 MSI Source Type Summary property when determining if a particular file is compressed or uncompressed.


MIME Table

The MIME table contains the association between a MIME context type and the file extension and the CLSID. This is used to generate the MIME information as a part of product advertisement.

The MIME table has the following columns.

Column | Type | Key | Nullable
ContentType | Text | Y | N
Extension_ | Text |  | N
CLSID | GUID |  | Y

Columns

ContentType
Content identifier, typically type/format.
Extension_
Associated extension (without dot). Foreign key into the Extension table.
CLSID
Associated CLSID.

Remarks

This table is referred to when the RegisterMIMEInfo action or the UnregisterMIMEInfo action is executed.


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, no action is taken on this MoveFile entry.
SourceName
Name of the source files to be moved or copied.

May be left blank (see the description of the SourceFolder column).

DestName
Name to be given to the original file after it is moved or copied.

If blank, the destination file is given the same name as the source file.

SourceFolder
Name of a property whose value is assumed to resolve to the full path to the source directory. If the SourceName column is left blank, the property named in the SourceFolder column is assumed to contain the full path to the source file itself (including the file name).
DestFolder
Name of a property whose value is assumed to resolve to the full path to the destination directory.

May contain wildcard characters (* and ?).

Options
Integer value specifying the MoveFile operating mode.

One of imfoEnum as follows.
Value | Meaning
0 (imfoCopy) | Copy the source file.
1 (imfoMove) | Move the source file.

Remarks

This table is processed by the MoveFiles action.


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 driver. A primary key for the table.
Attribute
Name of driver attribute. A primary key for the table.
Value
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 | Text |  | N

Columns

DataSource
Internal token name for data source. A primary key for the table.
Component_
External key into the Component table.
Description
The localized description registered for this data source.
DriverDescription
Associated driver which may be pre-existing.
Registration
A value of 0 in this column means that the data source is registered per machine. A value of 1 means the 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 ODBC key for the driver. This key is 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 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 localized description registered for this data source.
File_
The DLL file for translator 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 than from Translator. 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 the 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.
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 patch is located on.

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. To define a version independent program ID, place the corresponding ProgID in the Parent column.
Class_
Optional. A foreign key into the Class table. This column must be Null for a version independent ProgId.
Description
Optional, localized description of the associated program ID.
Icon_
Optional. A foreign key into the Icon table specifying 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
Name of property, must be uppercase if it can be set from the Loader.
Value
String value for property, may never be Null or an empty string.


PublishComponent Table

The PublishComponent table holds the information for cross-product advertisement of components and is used to generate component publishing information as a part of product advertisement.

The PublishComponent table has the following columns.

Column | Type | Key | Nullable
ComponentID | GUID | Y | N
Qualifier | Text | Y | N
AppData | Text |  | Y
Feature_ | Identifier |  | N
Component_ | Identifier |  | N

Columns

ComponentID
A string GUID that represents the component ID for the feature requested by an application. The component ID in the PublishComponent table is different than the component ID as described in 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. This qualifier is referred to by the MsiProvideQualifiedComponent function and the MsiEnumComponentQualifiers function.
AppData
An optional localizable text, owned and often parsed by the application. This can be retrieved with the MsiEnumComponentQualifiers function in the lpApplicationDataBuf buffer.
Feature_
External key into the Feature table.

External key to column one of the Feature table.

Component_
External key into the Component table.

External key to column one of the Component table.

Remarks

This table is referred to when the PublishComponents action or the UnpublishComponents action is executed.


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.

Positive numbers only.

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.

Non-negative numbers only.

Y
The vertical coordinate within the group of the upper-left corner of the bounding rectangle of the radio button.

Non-negative numbers only.

Width
The width of the button.

Non-negative numbers only.

Height
The height of the button.

Non-negative numbers only.

Text
The visible title to be assigned to the radio button. If the text is too long to be displayed on the control, it is truncated. If the button displays an icon or a bitmap, this entry contains the name of the picture (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. The string is divided into two parts, divided by a separator 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. 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 system font. Coordinates for the controls are relative to the billboard.

Positioning

The coordinates of the buttons are given relative to the group. If the coordinates of the group are changed, the buttons within the group remain in the same relative position to each other.

Formatting

The contents of the Value and Text fields are formatted by the MsiFormatRecord function when the control is created, so 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.


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 | KeyFormatted |  | Y
Value | KeyFormatted |  | Y
Component_ | Identifier |  | N

Columns

Registry
The key for this table.
Root
The predefined root key for the registry value.
Value | Meaning
0 | HKEY_CLASSES_ROOT
1 | HKEY_CURRENT_USER
2 | HKEY_LOCAL_MACHINE
3 | HKEY_USERS

Key
The key for the registry value.
Name
The registry value name. If Null, the data entered into the Value column are written to the default registry key.

If the Value column is Null, 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.

Value
The registry value.

KeyFormatted. If the Value is preceded by a pound symbol (#), 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_INTEGER).

  • If the value contains the sequence [~], then the value is interpreted as a Null-delimited list of strings (REG_MULTI_SZ).
  • 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 pound symbols (#), the value is interpreted and stored as a string, ignoring the first #.
Component_
External key into the Component table referencing the component that controls the installation of the registry value.

External key to column one of the Component table.

Remarks

The registry information is written out to the system registry when the corresponding component has been selected to be installed, either locally or run from source.

This table is referred to when the WriteRegistryValues action is executed.


RegLocator Table

The RegLocator table holds the information needed to find a file or directory using the registry.

The RegLocator table has the following columns.

Column | Type | Key | Nullable
Signature_ | Identifier | Y | N
Root | Integer |  | N
Key | RegPath |  | N
Name | KeyFormatted |  | Y
Type | Integer |  | Y

Columns

Signature_
The Signature_ 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 RegLocator table.

External key to column one of the Signature table.

Root
The predefined root key for the registry value.
Value | Root Key
0 | HKEY_CLASSES_ROOT
1 | HKEY_CURRENT_USER
2 | HKEY_LOCAL_MACHINE
3 | HKEY_USERS

Key
The key for the registry value.
Name
The registry value name.
Type
A Boolean value that determines if the registry value is a file name or a directory location.

If absent, Type is assumed to be 1, denoting a file name search.
Value | Meaning
0 | Directory
1 | File name

Remarks

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.


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 a particular file entry.
Component_
External key referencing the component that controls the file to be removed.

External key to column one of the Component table.

FileName
Name of the file to be removed. If this column is null, then the specified folder will be removed if it is empty.
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.
Value | Meaning
1 | Remove only when the associated component is being installed (iisLocal or iisSource).
2 | Remove only when the associated component is being removed (iisAbsent).
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
Directory_ | 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.
Directory_
External key into the Directory table indicating the directory in which the .ini file resides.

External key to column one of the Directory table.

Section
The .ini file section.
Key
The .ini file key below the section.
Value
The value to be deleted. The value is required when Action is 4.
Action
The type of modification to be made.
Value | Meaning
2 | Deletes .ini entry.
4 | Deletes a tag from a .ini entry.

Component_
External key into the Component table referencing the component that controls the deletion of the .ini value.

External key to column one of the Component table.

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.


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 | KeyFormatted |  | Y
Component_ | Identifier |  | N

Columns

RemoveRegistry
The key for this table.
Root
The predefined root key for the registry value.
Value | Meaning
0 | HKEY_CLASSES_ROOT
1 | HKEY_CURRENT_USER
2 | HKEY_LOCAL_MACHINE
3 | HKEY_USERS

Key
The key for the registry value.
Name
The 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.

Component_
External key into the Component table referencing the component that controls the deletion of the registry value.

External key to column one of the Component table.

Remarks

The registry information is deleted from the system registry when the corresponding component has been selected to be installed, either 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 a specified amount of disk space in any directory, depending 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 |  | Y
ReserveSource | DoubleInteger |  | Y

Columns

ReserveKey
Primary key that uniquely identifies a particular ReserveCost table entry.
Component_
Reserve a specified amount of space if this component is to be installed.

External key to column one of the Component Table.

ReserveFolder
This column contains the name of a property that is the full path to the destination directory. This property name will typically be the name of a directory in the Directory table or the name of a property set obtained using the Appsearch action. This will add the amount of disk space specified in ReserveLocal or ReserveSource to the volume cost of the device containing the directory.
ReserveLocal
Disk space to reserve if the linked component is installed locally.
ReserveSource
Disk space to reserve if the linked component is installed to run from the source location.

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.


Resource Table

The Resource table contains resource data to be written into executables or DLLs.

The Resource table has the following columns.

Column | Type | Key | Nullable
File_ | Identifier | Y | N
ResType | Integer | Y | N
ResId | Integer | Y | N
Data | Formatted |  | N

Columns

File_
File identifier, referencing the File table entry containing the file specification.

External key to column one of the File table.

ResType
Resource type to update.

Non-negative numbers only. Can be a user-defined resource type or one of the following predefined resource types.
Value | Resource Type | Meaning
9 | RT_ACCELERATOR | Accelerator table
21 | RT_ANICURSOR | Animated cursor
22 | RT_ANIICON | Animated icon
2 | RT_BITMAP | Bitmap resource
1 | RT_CURSOR | Hardware-dependent cursor resource
5 | RT_DIALOG | Dialog box
8 | RT_FONT | Font resource
7 | RT_FONTDIR | Font directory resource
12 | RT_GROUP_CURSOR | Hardware-independent cursor resource
14 | RT_GROUP_ICON | Hardware-independent icon resource
3 | RT_ICON | Hardware-dependent icon resource
4 | RT_MENU | Menu resource
11 | RT_MESSAGETABLE | Message-table entry
10 | RT_RCDATA | Application-defined resource (raw data)
6 | RT_STRING | String-table entry
16 | RT_VERSION | Version resource

ResId
Resource ID to update.

Non-negative numbers only.

Data
Data to write.

If the text string contains property parameters (a property name within square brackets), the current values for those properties are substituted into the string. If the resultant string begins with #x, the string is treated as a hexadecimal value, and the resource is updated with the binary value.

Remarks

This table is referred to when the UpdateResources action is executed.


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 SelfReg table has the following columns.

Column | Type | Key | Nullable
File_ | Identifier | Y | N
Cost | Integer |  | Y

Columns

File_
External key into the File table indicating the module that needs to be registered.

External key to column one of the File table.

Cost
The cost of registering the module.

Non-negative numbers only.


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 | Text |  | N
Event | Text |  | N
Arguments | KeyFormatted |  | 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 name service. The values are bitfields that can be combined into a single value that represents several operations.

The following values are only used during an install.
Value | Meaning
1 | Starts the service during the StartServices action.
2 | Stops the service during the StopServices action.
4 | <reserved>
8 | Deletes the service during the DeleteServices action.

The following values are only used during an uninstall
Value | Meaning
16 | Starts the service during the StartServices action.
32 | Stops the service during the StopServices action.
64 | <reserved>
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 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

None.


ServiceInstall Table

The ServiceInstall table is used to install a service.

The ServiceInstall table has the following columns.

Column | Type | Key | Nullable
ServiceInstall | Identifier | Y | N
Name | Text |  | N
DisplayName | Text |  | Y
ServiceType | DoubleInteger |  | N
StartType | DoubleInteger |  | N
ErrorControl | DoubleInteger |  | N
LoadOrderGroup | Text |  | Y
Dependencies | Formatted |  | Y
StartName | Formatted |  | Y
Password | Formatted |  | Y
Component_ | Identifier |  | N

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 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.

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.
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. Dependency on a group means that the service can run if at least one member of the group is running after an attempt to start all members of the group. Because services and service groups share the same name space, group names must have the prefix: SC_GROUP_IDENTIFIER.
StartName
The service will be 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. 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 Services installed with a user name and password cannot be rolled back when deleted.

Component_
External key to column one of the Component Table.

Remarks

This table has most of the parameters to the Win32 CreateService function.


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 | Text |  | N
Component_ | Identifier |  | N
Target | Identifier |  | N
Arguments | KeyFormatted |  | 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 Directory table specifying the directory into which the Shortcut file is created.

External key to column one of the Directory table.

Name
The name of the Shortcut to be created.
Component_
External key into the Component table specifying the component whose selection determines if the Shortcut is created (or deleted).

External key to column one of the Component table.

Target
The Shortcut target. This is the key into the Feature table in case of advertised Shortcuts. For non-advertised Shortcuts, it is a property that is expanded to a file or a folder that the Shortcut points to. For more information, see the CreateShortcuts action.

External key to column one of the Feature table or KeyFormatted.

Arguments
The command-line arguments for the Shortcut.
Description
The description of the Shortcut.
HotKey
The hotkey for the Shortcut.

Non-negative numbers only. The low-order byte contains the virtual-key code for the key, and the high-order byte contains modifier flags.

Icon_
External key to column one of the Icon table.
IconIndex
The icon index for the Shortcut.

Non-negative numbers only.

ShowCmd
The Show command for the application window.

The following values may be used. The values are exactly as defined for the Windows API function ShowWindow.
Value | Meaning
0 | SW_HIDE
1 | SW_SHOWNORMAL
2 | SW_SHOWMINIMIZED
3 | SW_SHOWMAXIMIZED
4 | SW_SHOWNOACTIVATE
5 | SW_SHOW
6 | SW_MINIMIZE
7 | SW_SHOWMINNOACTIVE
8 | SW_SHOWNA
9 | SW_RESTORE
10 | SW_SHOWDEFAULT
10 | SW_MAX

WkDir
The name of the property that has the path of the working directory for the Shortcut.

Remarks

The Shortcuts are created only if the IShellLink interface is present on the system. An advertised shortcut is created when the corresponding feature has been enabled. A non-advertised shortcut is created when the corresponding component has been selected to be installed, either locally or run from source.

This table is referred to when the CreateShortcuts action and the RemoveShortcuts action is executed.


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 represents a unique file signature.
FileName
The name of the file.
MinVersion
The minimum version of the file. If specified, the file under inspection must have a version that is at least equal to MinVersion.
MaxVersion
The maximum version of the file. If specified, the file under inspection must have a version that is at most equal to MaxVersion.
MinSize
The minimum size of the file. If specified, the file under inspection must have a size that is at least equal to MinSize.

Non-negative numbers only.

MaxSize
The maximum size of the file. If specified, the file under inspection must have a size that is at most equal to MaxSize.

Non-negative numbers only.

MinDate
The minimum creation date of the file. If specified, the file under inspection must have a creation date that is at least equal to MinDate.

Non-negative numbers only.

MaxDate
The maximum creation date of the file. If specified, the file under inspection must have a creation date that is at most equal to MaxDate.

Non-negative numbers only.

Languages
The languages supported by the file.

Remarks

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.


TextStyle Table

The TextStyle table lists the different text styles used in the text controls.

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
Name of the style. This name is embedded in the texts to indicate a style change.
FaceName
A string indicating the name of the font used.

The string must be no more than 31 characters long.

Size
The size of the font used. This is in the installer units. An installer unit is equal to one-twelfth of the height of the system font.

Non-negative numbers only.

Color
A four-byte integer indicating the color of the string in the RGB format.

The color value is specified in RGB format.

Red, green, and blue each have a range of 0-255. Blank signifies the default color.

StyleBits
A combination of bits indicating the style of the string.

A combination of the following style bits.
Bit | Style
0 | Bold
1 | Italic
2 | Underline
3 | Strike out


TypeLib Table

The TypeLib table contains the information that needs to be placed in the registry for the advertisement and registration of type libraries.

The TypeLib table has the following columns.

Column | Type | Key | Nullable
LibID | GUID | Y | N
Language | Integer | Y | N
Version | Integer |  | Y
Description | Text |  | Y
Directory_ | Identifier |  | Y
Feature_ | Identifier |  | N
Component_ | Identifier |  | N
Cost | DoubleInteger |  | Y

Columns

LibID
The GUID that identifies the library.
Language
The language of the type library.

Non-negative numbers only.

Version
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
Description of the library.
Directory_
External key into the Directory table that identifies the Help path for the type library. This column is ignored during advertising.

External key to column one of the Directory table.

Feature_
External key into the Feature table specifying the feature to be advertised or installed for the type library to be operational.

External key to column one of the Feature table.

Component_
External key into the Component table identifying the component belonging to Feature_ whose key file is the type library being advertised/ registered.

External key to column one of the Component table.

Cost
The cost associated with the registration of the type library. This column is optional.

Non-negative numbers only.

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 on how the installer should perform an upgrade of a product and how to handle installations when related versions of the product are already installed.

The Upgrade table has the following columns.

Column | Type | Key | Nullable
UpgradeCode | GUID | Y | N
ProductVersion | Text | Y | N
Operator | Integer | Y | N
Features | Text |  | N
Property | Identifier |  | N

Columns

UpgradeCode
This column contains a unique UpgradeCode property representing a set of products that are related to the pending product upgrade. Products already installed and having this UpgradeCode may be removed and replaced by the pending upgrade or the current installation may be blocked.
ProductVersion
This is the version of the product that it to be compared to any related products that are already installed. Whether or not this version replaces an installed version of the product depends upon the evaluation of the Operator column.
Operator
This column contains an operator that changes the current installation dependent upon whether another version of the product is already installed. The following table lists the possible operations. To combine these operations, add their values and use the sum in the Operator column. For example, setting the Operator column to 3 specifies that the installation be blocked if a newer upgrade of the product is already installed. The type of the operator should be the same as the Type column of the CustomAction table.
Value | Operation
0 | If there is another version of the product already installed, then uninstall it.
1 | If there is another version of the product already installed, then block the installation.
2 | Check if the installed version of the product is greater than the ProductVersion column.
4 | Check if the installed version of the product is less than the ProductVersion column.
8 | Check if the installed version of the product equals the ProductVersion column.
16 | If there is another version of the product already installed, then migrate the product settings from it.

Features
The features listed in this column are removed from the installed product when installing a newer version of the product.
Property
The property in this column is set to the product code if the FindRelatedProducts action finds any related products already installed. If more than one product is found, this property is set to a semi-colon delimited list of product codes.

Remarks

The Upgrade table is used by the FindRelatedProducts action, BlockInstall action, MigrateFeatureSettings action and the RemoveOldProducts action.


Verb Table

The Verb table contains command-verb information associated with file extensions that must be generated as a part of the 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 | KeyFormatted |  | Y

Columns

Extension_
The extension associated with the table row.

External key to column one of the Extension table.

Verb
The verb for the command.
Sequence
The sequence that the commands should appear in. 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.
Command
The command text.
Argument
Value for the command arguments.

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. All the columns for all tables are listed. 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 method.

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.


_Required Table

The _Required table is a system table that contains the number of primary keys for all the tables in the database. It is only used during the database validation process.

Column | Type | Key | Nullable
Description | Text |  | Y
KeyCount | Integer |  | N
Table | Identifier | Y | N
Value | Text | Y | N

Columns

Description
Description of required value.
KeyCount
Number of primary keys (determines how to parse value string).
Table
Name of table.
Value
Required value.


_Sequence Table

The _Sequence table is a system table that lists the sequencing restrictions of all actions used in the installer database. Some actions in the installer have pre- and post-conditional actions. This table is used during the database validation process to ensure that all sequenced actions are in the correct order. Sequencing restrictions, if any, are listed in the individual action topics.

Column | Type | Key | Nullable
Action | Identifier | Y | N
After | Integer |  | N
Dependent | Identifier | Y | N
Optional | Integer |  | N

Columns

Action
Name of action.
After
Boolean for whether action comes after Dependent action.
Dependent
Dependent action.
Optional
Boolean for whether dependent action is optional.


_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 method.


_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
The minimum value allowed. May be the minimum value for an integer or the minimum value for a date or version string.

Non-negative numbers only.

MaxValue
The maximum value allowed. May be the maximum value for an integer or the maximum value for a date or version string.

Non-negative numbers only.

KeyTable
For an external key column, name of the external table to which the data must link. May be a list of tables separated by semicolons.
KeyColumn
For an external key column, column number in the table specified by KeyTable to which the data must link.

Range 1-32.

Category
A category of string or data that defines the type of data contained in the column.

This string must be one of the types described in Column Data Types. The validation table is used to ensure that the table entries are the correct types as specified by the Category column.

Set
The set of possible values allowed, separated by semicolons. Most often used when dealing with enums.
Description
The description of the data that is stored in the column.


Database Access

Because the installation database contains all the information about the installation of a product, the Microsoft® Windows® installer provides many standard features that enable the user to access, retrieve, and manipulate the information in the database tables. Database access is required to create a custom installation package.

The material in this section is primarily for developers who want to write tools that create new installer packages and who therefore 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. Some 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 installer and component management technology, see About Windows Installer.

The installer has many standard features for database access. The About Database Access section gives a general description of installer features providing table querying and manipulation capabilities. For situations that are not addressed directly by these standard access features, additional database access functionality can be created by using Custom Actions.

The Accessing Databases section describes common procedures used to get, open, and change information in a database table.

The Database Access Reference describes in detail all of the access functions available to manipulate the installation database.


About Database Access

The standard database access features provided by the Microsoft® Windows® installer enable the user to customize the installation process to his own requirements. Many customizations require similar kinds of database access, the most common being the retrieval of information from the database, changing or adding information, and finally saving the changes. The following are lists of standard database access features that retrieve, change, and save information in the installation database. These features are implemented using procedures described in the Accessing Databases section.

Access Features That Retrieve Information From The Database

Access Features That Change The Database

Access Features That Save Changes To The Database


Access Features That Retrieve Information From The Database

  • Query a table using Structured Query Language (SQL) by Working with Queries .
  • Extract information from tables as text archives by Importing and Exporting.
  • Read a particular record field by Working with Records.
  • Check the state of an installer feature or component by Working with Features and Components.
  • Locate the source or target of a particular folder by Working with Folder Locations.
  • Examine how the user interface appears to the user by Previewing the User Interface.


Access Features That Change The Database

  • Instigate a sequence of actions that change the database by Running Actions.
  • Modify a table using Structured Query Language (SQL) by Working with Queries .
  • Enter information into a table as a text archive by Importing and Exporting.
  • Control the installation by working with Installer Properties.
  • Create and set new records by Working with Records.
  • Perform database operations by Working with Transforms.
  • Combine the information in two databases by Merging Databases.
  • Modify an installer feature or component by Working with Features and Components.
  • Change the target of a folder by Working with Folder Locations.


Access Features That Save Changes To The Database

  • Save the changes made to database tables by Committing Databases.


Accessing Databases

Utilizing the standard database access features involves using the following procedures for obtaining a handle and accessing the installation database. The About Database Access section provides lists of standard access features that are provided by the installer with links to the appropriate procedures. The following is a list of the most common to use to access the database. Note that before working with a database you must first obtain a handle to it and then to save any changes you must commit the database.

  • Obtaining A Database Handle
  • Working with Queries
  • Running Actions
  • Importing and Exporting
  • Merging Databases
  • Working with Transforms
  • Working with Records
  • Working with Installer Properties
  • Working with Folder Locations
  • Working with Features and Components
  • Previewing the User Interface
  • Committing Databases


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. You obtain a handle to the database in one of two ways:
    • If an installation is in progress, you get a handle to the active database by calling the MsiGetActiveDatabase function.
    • Otherwise, to open any specified database, call the MsiOpenDatabase function.
  2. Once you have a database open, you can call a variety of functions to obtain information about the database or to manipulate the database. For example, you can:
    • Obtain a record that contains all primary keys of the specified database by calling the MsiDatabaseGetPrimaryKeys function.
    • Check the current state of a 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. You can check to see if 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 and also 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.
  • Develop the partial component databases separately.
  • Merge each component database into the main product database by calling the MsiDatabaseMerge function.


Working with Transforms

Transforms greatly increase the flexibility of application installation by providing a way of recording changes to a database without altering the original database. Transforms are used extensively for upgrading and patching products. Merges and Transforms can operate on entire databases.

The following procedure describes a scenario in which a transform is used to localize a recent upgrade in the most efficient manner.

To localize to French a recent upgrade of a product in English:
  1. Localize to French a snapshot of an English version 1.0 of an application.
  2. Develop the English version from version 1.0 to version 2.0.
  3. Create a transform from the English version 1.0 to the English version 2.0 by calling MsiDatabaseGenerateTransform.
  4. Apply this transform to the French version 1.0 to obtain a French version 2.0 by calling MsiDatabaseApplyTransform.

Following the preceding procedure results in a French version that requires minimal work to bring it to French version 2.0.


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.


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 Installer Properties

The installer uses a number of properties to control installation. A list of the properties can be found in the Property Reference topic.

Functions that get installer properties:

  • To obtain the current properties, 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.

Functions that set installer properties:

  • To set properties, call the MsiSetProperty function.
  • To set the installation state, call the MsiSetMode function.


Running Actions

You can use the installer functions to run specific actions or to instigate action sequences. These actions can be standard actions, which ship with the installer, or they can be 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 then processes the error.


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.


Working with Features and Components

There are several functions that change the installation of product components and features. The following procedure describes how to change the 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 will be 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.


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.


Database Access Reference

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

You can use the following general access functions in your application:

MsiDatabaseCommit

MsiDatabaseGetPrimaryKeys

MsiDatabaseIsTablePersistent

MsiDatabaseOpenView

MsiGetActiveDatabase

MsiOpenDatabase

MsiViewClose

MsiViewExecute

MsiViewFetch

MsiViewGetError

MsiViewModify

Database Management Functions

You can use the following access functions to manage the database:

MsiCreateTransformSummaryInfo

MsiDatabaseApplyTransform

MsiDatabaseExport

MsiDatabaseGenerateTransform

MsiDatabaseImport

MsiDatabaseMerge

MsiGetDatabaseState

Record Processing Functions

You can use the following functions to process database records:

MsiCreateRecord

MsiRecordClearData

MsiRecordDataSize

MsiRecordGetFieldCount

MsiRecordGetInteger

MsiRecordGetString

MsiRecordIsNull

MsiRecordReadStream

MsiRecordSetInteger

MsiRecordSetStream

MsiRecordSetString

Summary Information Property Functions

You can use the following functions with the summary information properties:

MsiGetSummaryInformation

MsiSummaryInfoGetProperty

MsiSummaryInfoGetPropertyCount

MsiSummaryInfoPersist

MsiSummaryInfoSetProperty

Installer State Access Functions

You can use the following functions to change or monitor the installer state:

MsiGetLanguage

MsiGetLastErrorRecord

MsiGetMode

MsiGetProperty

MsiSetProperty

MsiSetMode

Installer Action Functions

You can use the following functions to access the installer actions:

MsiDoAction

MsiEvaluateCondition

MsiProcessMessage

MsiSequence

Installer Location Functions

You can use the following functions to access the installer folder location:

MsiGetSourcePath

MsiGetTargetPath

MsiSetTargetPath

Installer Selection Functions

You can use the following functions to access the installer selection state:

MsiGetComponentState

MsiGetFeatureCost

MsiGetFeatureState

MsiGetFeatureValidStates

MsiSetComponentState

MsiSetFeatureState

MsiSetInstallLevel

MsiVerifyDiskSpace

User Interface Functions

You can use the following functions to preview user interface dialog boxes:

MsiEnableUIPreview

MsiPreviewBillboard

MsiPreviewDialog

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}]

  • To add records to a table.

    INSERT INTO {table} ({column-list}) VALUES ({constant-list}) [TEMPORARY]

  • To add a table.

    CREATE TABLE {table} ( {column} [CHAR [( {size} )] | CHARACTER [( {size} )] | LONGCHAR | SHORT | INT | INTEGER | LONG | OBJECT ] [NOT NULL] [TEMPORARY][LOCALIZABLE] [, column...][, ...] PRIMARY KEY column [, column][, ...] )[HOLD]

  • To remove a table.

    DROP TABLE {table}

  • To add a column.

    ALTER TABLE {table} ADD {column} [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 period 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.

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. Table names that clash with SQL keywords must be enclosed in two grave accent marks `` (ASCII value 96). Table names are limited to 31 characters and cannot include a period.

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}. Column names that clash with SQL keywords must be enclosed in quotation marks " ". If the column is qualified as {tablename.column} and if there is a need to escape the identifier, the table name and the column must be individually escaped as {`tablename`.`column`}. Column names cannot include a period.

The table and column names are case-sensitive, even if ODBC databases are used. However, SQL keywords are not case-sensitive. Only inner joins are supported, specified by a comparison of columns from different tables.

Tables may contain from 1 to 32 columns. Table and column names are not constrained except that they are limited to 31 characters. 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 will always group together.

Tables may not contain more than one column of type 'object'.


MsiCreateRecord

The MsiCreateRecord function creates a new record object with the specified number of fields.

MSIHANDLE MsiCreateRecord(
  unsigned int cParams  // the number of data fields
);

Parameters

cParams
Specifies the number of fields the record will have. This value is limited by memory.

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.

QuickInfo

Windows NT: Requires version 4.0 or later. Available as a redistributable for Windows NT 4.0.
Windows: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Windows CE: Unsupported.
Header: Declared in msiquery.h.
Import Library: Use msi.lib.

See Also

Database Access Reference, 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
Handle to the database that contains the new database Summary Information.
hDatabaseReference
Handle to the database that contains the original Summary Information.
SzTransformFile
The name of the transform that the Summary Information is being added to.
iErrorConditions
The error conditions that should be suppressed when the transform is applied. Choose either:
0x0000 None of the following conditions.

or one or more of the following values:
Value | Meaning
0x0001 | Adding a row that already exists.
0x0002 | Deleting a row that doesn't exist.
0x0004 | Adding a table that already exists.
0x0008 | Deleting a table that doesn't exist.
0x0010 | Updating a row that doesn't exist.

iValidation
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.
Value | Meaning
0x0000 - | Validate no properties.
0x0001 - | Default language must match base database.
0x0002 - | Product must match base database.
0x0004 - | Platform must match base database.

Validate product version flags.
Value | Meaning
0x0008 - | Check major version only.
0x0010 - | Check major and minor versions only.
0x0020 - | Check major, minor, and update versions.

Product version relationship flags.
Value | Meaning
0x0040 - | Applied database version < base database version.
0x0080 - | Applied database version <= base database version.
0x0100 - | Applied database version = base database version.
0x0200 - | Applied database version >= base database version.
0x0400 - | Applied database version > base database version.

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.


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
Handle to database to transform.
szTransformFile
Specifies the name of the transform file to apply.
iErrorConditions
Error conditions that should be suppressed. This parameter (can or must) be (one, any, one or more) of the following values.
Value | Meaning
0x0001 | Adding a row that already exists.
0x0002 | Deleting a row that doesn't exist.
0x0004 | Adding a table that already exists.
0x0008 | Deleting a table that doesn't exist.
0x0010 | Updating a row that doesn't exist.

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.

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

QuickInfo

Windows NT: Requires version 4.0 or later. Available as a redistributable for Windows NT 4.0.
Windows: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Windows CE: Unsupported.
Header: Declared in msiquery.h.
Import Library: Use msi.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT.

See Also

Database Access Reference, Database Management Functions


MsiDatabaseCommit

The MsiDatabaseCommit function commits changes to a database.

UINT MsiDatabaseCommit(
  MSIHANDLE hDatabase    // database handle
);

Parameters

hDatabase
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.

QuickInfo

Windows NT: Requires version 4.0 or later. Available as a redistributable for Windows NT 4.0.
Windows: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Windows CE: Unsupported.
Header: Declared in msiquery.h.
Import Library: Use msi.lib.

See Also

Database Access Reference, 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
Handle to the database.
szTableName
Specifies the name of the table to export.
szFolderPath
Specifies the name of the folder that contains archive files.
szFileName
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.

QuickInfo

Windows NT: Requires version 4.0 or later. Available as a redistributable for Windows NT 4.0.
Windows: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Windows CE: Unsupported.
Header: Declared in msiquery.h.
Import Library: Use msi.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT.

See Also

Database Access Reference, 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,               // reserved argument, not used
  int iReserved2                // reserved argument, not used
);

Parameters

hDatabase
Handle to the database that includes the changes.
hDatabaseReference
Handle to the database that does not include the changes.
szTransformFile
The name of the generated transform file. This is optional.
iReserved1
This is a reserved argument and is not used.
iReserved2
This is a reserved argument and is not used.

Return Values

ERROR_NO_DATA
The two databases are identical.
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.

Since the list delimiter for transforms, sources and patches is a semicolon, this character should not be used for these 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.

QuickInfo

Windows NT: Requires version 4.0 or later. Available as a redistributable for Windows NT 4.0.
Windows: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Windows CE: Unsupported.
Header: Declared in msiquery.h.
Import Library: Use msi.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT.

See Also

Database Access Reference, Database Management Functions


MsiDatabaseGetPrimaryKeys

The MsiDatabaseGetPrimaryKeys function returns a record containing the names of all the primary key columns.

UINT MsiDatabaseGetPrimaryKeys(
  MSIHANDLE hDatabase,   // database handle
  LPCTSTR szTableName,   // name of table
  MSIHANDLE *phRecord    // handle for record
);

Parameters

hDatabase
Handle to the database.
szTableName
Specifies the name of the table from which to obtain primary key names.
phRecord
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.

QuickInfo

Windows NT: Requires version 4.0 or later. Available as a redistributable for Windows NT 4.0.
Windows: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Windows CE: Unsupported.
Header: Declared in msiquery.h.
Import Library: Use msi.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT.

See Also

Database Access Reference, 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
Handle to the database.
szFolderPath
Specifies the path to the folder containing archive files.
szFileName
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, the "05SummaryInformation" stream is written. This stream contains standard properties that are defined by COM and browseable by Windows® Explorer. The table rows consisting of pairs of property ID numbers with corresponding data values are written to the property stream.

When you use the MsiDatabaseImport function to import a text archive table named _SummaryInformation into an ODBC database, a normal table is created. If the data is a valid integer, the database interprets this integer as an integer property. If the data can be parsed as a date or date/time value (consisting of digits separated by slashes), the database interprets this value as a data/time value. Otherwise, the database interprets the data as a string value. Date values can have two formats: yyyy/mm/dd (time is entered as 0) or yyyy/mm/dd/hh/mm/ss (24-hour time). The summary information is customarily generated for new files by the release build process.

QuickInfo

Windows NT: Requires version 4.0 or later. Available as a redistributable for Windows NT 4.0.
Windows: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Windows CE: Unsupported.
Header: Declared in msiquery.h.
Import Library: Use msi.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT.

See Also

Database Access Reference, 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
Handle to the database to which the relevant table belongs.
szTableName
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.

QuickInfo

Windows NT: Requires version 4.0 or later. Available as a redistributable for Windows NT 4.0.
Windows: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Windows CE: Unsupported.
Header: Declared in msiquery.h.
Import Library: Use msi.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT.

See Also

Database Access Reference, General Database Access Functions


MsiDatabaseMerge

The MsiDatabaseMerge function merges two databases together, allowing duplicate rows.

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
Handle to the base database.
hDatabaseMerge
Handle to the database to merge into the base database.
szTableName
Specifies the name of the table to receive merge conflict information.

Return Values

ERROR_FUNCTION_FAILED
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.

Remarks

The MsiDatabaseMerge function merges two databases. The data in the base database dominates in any merge conflicts. If tables of the same name in both databases do not match in the number of primary keys, column types, number of columns, or column names, or if the tables share the same primary key names but the data in the other columns differs, the MsiDatabaseMerge function fails. If merge conflicts are reported, the Error table that is created contains two columns. The first column specifies the name of the table that has merge conflicts. The second column contains the number of rows in the table that has merge conflicts.

QuickInfo

Windows NT: Requires version 4.0 or later. Available as a redistributable for Windows NT 4.0.
Windows: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Windows CE: Unsupported.
Header: Declared in msiquery.h.
Import Library: Use msi.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT.

See Also

Database Access Reference, Database Management Functions


MsiDatabaseOpenView

The MsiDatabaseOpenView function prepares a database query and creates a view object.

UINT MsiDatabaseOpenView(
  MSIHANDLE hDatabase,   // database handle
  LPCTSTR szQuery,       // SQL query to be prepared
  MSIHANDLE *phView      // returned view if TRUE
);

Parameters

hDatabase
Handle to the database to which you want to open a view object.
szQuery
Specifies a SQL query string for querying the database. For correct syntax, see SQL Syntax.
phView
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.

QuickInfo

Windows NT: Requires version 4.0 or later. Available as a redistributable for Windows NT 4.0.
Windows: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Windows CE: Unsupported.
Header: Declared in msiquery.h.
Import Library: Use msi.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT.

See Also

Database Access Reference, 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
Handle to the installation.
szAction
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 engine 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 engine 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".

QuickInfo

Windows NT: Requires version 4.0 or later. Available as a redistributable for Windows NT 4.0.
Windows: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Windows CE: Unsupported.
Header: Declared in msiquery.h.
Import Library: Use msi.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT.

See Also

Database Access Reference, Installer Action Functions


MsiEnableUIPreview

The MsiEnableUIPreview function enables preview mode of the user interface to facilitate authoring of user-interface dialog boxes.

UINT MsiEnableUIPreview(
  MSIHANDLE hDatabase,  // database handle
  MSIHANDLE *phPreview  // returned handle for UI preview capability
);

Parameters

hDatabase
Handle to the database.
phPreview
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.

QuickInfo

Windows NT: Requires version 4.0 or later. Available as a redistributable for Windows NT 4.0.
Windows: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Windows CE: Unsupported.
Header: Declared in msiquery.h.
Import Library: Use msi.lib.

See Also

Database Access Reference, 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
Handle to the installation.
szCondition
Specifies the conditional expression.

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 MsiEvaluateCondition function uses the following conditional statement 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

All symbol names and values are case-sensitive, except environment variable names, which are not case-sensitive.

Operators are not case-sensitive.

Literal text must be enclosed in double quotes.

Floating point numeric values are not supported.

Operators and precedence: same as BASIC and SQL languages.

Arithmetic operators are not supported.

Supported operators: OR AND NOT Xor Eqv Imp < <= = <> >= > ().

Non-existent property values are treated as empty strings.

Comparison of an integer with a string or property value that cannot be converted to an integer is always iecFalse, except for the comparison operator '<>', which returns iecTrue.

Parentheses can be used to override operator precedence.

For string comparisons, a tilde '~' prefixed to the operator performs a comparison that is not case-sensitive.

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.

The following table shows the logical operators used by the MsiEvaluateCondition function, in high to low 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.

The following table shows the comparison operators used by the MsiEvaluateCondition function. 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.

The following table shows the substring operators used by the MsiEvaluateCondition function. These 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.

The following table shows the bitwise numeric operators used by the MsiEvaluateCondition function. 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.

The following table shows the feature and component state values used by the MsiEvaluateCondition function.

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.

Note 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.

QuickInfo

Windows NT: Requires version 4.0 or later. Available as a redistributable for Windows NT 4.0.
Windows: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Windows CE: Unsupported.
Header: Declared in msiquery.h.
Import Library: Use msi.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT.

See Also

Database Access Reference, 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
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
Handle to the record to format. The template string must be stored in record field 0 followed by referenced data parameters.
szResultBuf
Specifies the buffer to return the formatted string to.
pcchResultBuf
Specifies the in/out character count.

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.
    • If a substring of the form [$componentkey] is found, it is replaced by the installation directory of the component, with the value componentkey used as a key into the Component table, taking into account the Component.Action column state. If the component is selected to be installed locally, it is replaced by the target directory. If the component is selected to run from source, it is replaced by the source directory. If the component is not selected or if the component is missing, it is replaced by a null string.
    • 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.

QuickInfo

Windows NT: Requires version 4.0 or later. Available as a redistributable for Windows NT 4.0.
Windows: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Windows CE: Unsupported.
Header: Declared in msiquery.h.
Import Library: Use msi.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT.


MsiGetActiveDatabase

The MsiGetActiveDatabase function returns the active database for the installation.

MSIHANDLE MsiGetActiveDatabase(
  MSIHANDLE hInstall    // installer handle
);

Parameters

hInstall
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 return value can be the following:

ERROR_INVALID_HANDLE
An invalid or inactive handle was supplied.

Remarks

The MsiGetActiveDatabase function is used to access the database in use by the running the installation.

QuickInfo

Windows NT: Requires version 4.0 or later. Available as a redistributable for Windows NT 4.0.
Windows: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Windows CE: Unsupported.
Header: Declared in msiquery.h.
Import Library: Use msi.lib.

See Also

Database Access Reference, 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
Handle to the installation.
szComponent
Specifies the component name within the product.
piInstalled
Specifies the returned current installed state. This parameter can be one of the following values.
Value | Meaning
INSTALLSTATE_ABSENT | The component is not installed.
INSTALLSTATE_BADCONFIG | The configuration data is corrupt.
INSTALLSTATE_DEFAULT | The component will be installed in the default location: local or source.
INSTALLSTATE_FREECACHE | The source files must be released from the client cache.
INSTALLSTATE_INCOMPLETE | The installation is suspended or in progress.
INSTALLSTATE_INVALIDARG | An invalid parameter was passed to the function.
INSTALLSTATE_LOCAL | The component is installed on the local drive.
INSTALLSTATE_LOCKCACHE | The source files in the client cache are locked.
INSTALLSTATE_MOREDATA | The buffer overflow is returned.
INSTALLSTATE_SOURCE | The component will run from the source, CD, or network.
INSTALLSTATE_SOURCEABSENT | The component cannot run from the source because the source is unavailable.
INSTALLSTATE_UNKNOWN | An unrecognized product or feature name was passed to the function.

piAction
Specifies 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_FEATURE
An unknown feature was requested.

QuickInfo

Windows NT: Requires version 4.0 or later. Available as a redistributable for Windows NT 4.0.
Windows: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Windows CE: Unsupported.
Header: Declared in msiquery.h.
Import Library: Use msi.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT.

See Also

Database Access Reference, Installer Selection Functions


MsiGetDatabaseState

The MsiGetDatabaseState function returns the state of the database.

MSIDBSTATE MsiGetDatabaseState(
  MSIHANDLE hDatabase    // database handle
);

Parameters

hDatabase
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.

QuickInfo

Windows NT: Requires version 4.0 or later. Available as a redistributable for Windows NT 4.0.
Windows: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Windows CE: Unsupported.
Header: Declared in msiquery.h.
Import Library: Use msi.lib.

See Also

Database Access Reference, 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
Handle to the installation.
szFeature
Specifies the name of the feature.
iCostTree
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_PRODUCT | Unsupported.
MSICOSTTREE_SELFONLY | The feature only is included in the cost.

iState
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
Specifies the returned 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

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.

QuickInfo

Windows NT: Requires version 4.0 or later. Available as a redistributable for Windows NT 4.0.
Windows: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Windows CE: Unsupported.
Header: Declared in msiquery.h.
Import Library: Use msi.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT.

See Also

Database Access Reference, 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
Handle to the installation.
szFeature
Specifies the feature name within the product.
piInstalled
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_ABSENT | The feature was uninstalled.
INSTALLSTATE_LOCAL | The feature was installed on the local drive.
INSTALLSTATE_SOURCE | The feature must run from source, CD, or network.
INSTALLSTATE_DEFAULT | The feature will be installed in the default location: local or source.
INSTALLSTATE_LOCKCACHE | The source files are locked in the client cache.
INSTALLSTATE_FREECACHE | The source files are released from the client cache.

piAction
Specifies 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.

QuickInfo

Windows NT: Requires version 4.0 or later. Available as a redistributable for Windows NT 4.0.
Windows: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Windows CE: Unsupported.
Header: Declared in msiquery.h.
Import Library: Use msi.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT.

See Also

Database Access Reference, Installer Selection Functions


MsiGetFeatureValidStates

The MsiGetFeatureValidStates function returns a valid installation state.

UINT MsiGetFeatureValidStates(
  MSIHANDLE hInstall,            // installer handle
  LPCTSTR szFeature,             // feature name
  DWORD *dwInstallState          // install state
);

Parameters

hInstall
Handle to the installation.
szFeature
Specifies the feature name.
dwInstallState
Specifies the location to hold the valid installation states. This parameter will be a combination of the following values. For each valid install state, a bit is set of value: (1 << INSTALLSTATE).
Value | Meaning
1 << INSTALLSTATE_ABSENT | The feature can be uninstalled.
1 << INSTALLSTATE_ADVERTISED | The feature can be advertised.
1 << INSTALLSTATE_LOCAL | The feature can be installed on the local drive.
1 << INSTALLSTATE_SOURCE | The feature can be configured to run from source, CD, or network.
1 << 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

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.

QuickInfo

Windows NT: Requires version 4.0 or later. Available as a redistributable for Windows NT 4.0.
Windows: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Windows CE: Unsupported.
Header: Declared in msiquery.h.
Import Library: Use msi.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT.

See Also

Database Access Reference, 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
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.

QuickInfo

Windows NT: Requires version 4.0 or later. Available as a redistributable for Windows NT 4.0.
Windows: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Windows CE: Unsupported.
Header: Declared in msiquery.h.
Import Library: Use msi.lib.

See Also

Database Access Reference, Installer State Access Functions


MsiGetLastErrorRecord

The MsiGetLastErrorRecord function returns the error record that was last returned for the calling process.

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 MSI 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 install 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

QuickInfo

Windows NT: Requires version 4.0 or later. Available as a redistributable for Windows NT 4.0.
Windows: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Windows CE: Unsupported.
Header: Declared in msiquery.h.
Import Library: Use msi.lib.

See Also

Database Access Reference, Installer State Access Functions


MsiGetMode

The MsiGetMode function returns one of the Boolean internal installation states.

BOOL MsiGetMode(
  MSIHANDLE hInstall,    // installer handle
  MSIRUNMODE iRunMode    // run mode
);

Parameters

hInstall
Handle to the installation.
iRunMode
Specifies the run mode. This parameter must be 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.

Return Values

If the function succeeds, the return value is the BOOL internal installer state.

If the function fails, the return value is FALSE.

QuickInfo

Windows NT: Requires version 4.0 or later. Available as a redistributable for Windows NT 4.0.
Windows: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Windows CE: Unsupported.
Header: Declared in msiquery.h.
Import Library: Use msi.lib.

See Also

Database Access Reference, 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
Handle to the installer.
szName
Specifies the name of the property.
szValueBuf
Specifies the buffer for the value of the property.
pchValueBuf
Specifies the in-buffer character count.

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.

QuickInfo

Windows NT: Requires version 4.0 or later. Available as a redistributable for Windows NT 4.0.
Windows: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Windows CE: Unsupported.
Header: Declared in msiquery.h.
Import Library: Use msi.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT.

See Also

Database Access Reference, Installer State Access 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
Handle to the installation.
szFolder
Indicates 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
Specifies a buffer to return the full path.
pcchPathBuf
Specifies the in/out character count.

Return Values

ERROR_BAD_PATHNAME
An invalid path was supplied.
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.

QuickInfo

Windows NT: Requires version 4.0 or later. Available as a redistributable for Windows NT 4.0.
Windows: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Windows CE: Unsupported.
Header: Declared in msiquery.h.
Import Library: Use msi.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT.

See Also

Database Access Reference, Installer Location Functions


MsiGetSummaryInformation

The MsiGetSummaryInformation function obtains a handle to the _SummaryInformation stream for an installer database.

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
Handle to the database.
szDatabasePath
Specifies the path to the database.
uiUpdateCount
Specifies the maximum number of updated values.
phSummaryInfo
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.

QuickInfo

Windows NT: Requires version 4.0 or later. Available as a redistributable for Windows NT 4.0.
Windows: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Windows CE: Unsupported.
Header: Declared in msiquery.h.
Import Library: Use msi.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT.

See Also

Database Access Reference, 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
Handle to the installation.
szFolder
Specifies the folder identifier. This is a primary key in the Directory table.
szPathBuf
Specifies a buffer to return the full path.
pcchPathBuf
Specifies the in/out buffer character count.

Return Values

ERROR_BAD_PATHNAME
An invalid path was supplied.
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.

QuickInfo

Windows NT: Requires version 4.0 or later. Available as a redistributable for Windows NT 4.0.
Windows: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Windows CE: Unsupported.
Header: Declared in msiquery.h.
Import Library: Use msi.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT.

See Also

Database Access Reference, Installer Location Functions


MsiOpenDatabase

The MsiOpenDatabase function opens a database file for data access.

UINT MsiOpenDatabase(
  LPCTSTR szDatabasePath,  // path to database
  LPCTSTR szPersist,       // output database or predefined
                           // persist mode
  MSIHANDLE *phDatabase    // location to return database handle
);

Parameters

szDatabasePath
Specifies the full path or relative path to the database file.
szPersist
Specifies 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.

phDatabase
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

The MsiOpenDatabase function initiates database access. This function cannot be used for a running installation. The database must be opened in transaction, create, or direct mode for changes to be retained. Create mode creates a new installer database

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.

QuickInfo

Windows NT: Requires version 4.0 or later. Available as a redistributable for Windows NT 4.0.
Windows: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Windows CE: Unsupported.
Header: Declared in msiquery.h.
Import Library: Use msi.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT.

See Also

Database Access Reference, 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
Handle to the preview.
szControlName
Specifies the name of the host control.
szBillboard
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.

QuickInfo

Windows NT: Requires version 4.0 or later. Available as a redistributable for Windows NT 4.0.
Windows: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Windows CE: Unsupported.
Header: Declared in msiquery.h.
Import Library: Use msi.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT.

See Also

Database Access Reference, 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
Handle to the preview.
szDialogName
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.

QuickInfo

Windows NT: Requires version 4.0 or later. Available as a redistributable for Windows NT 4.0.
Windows: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Windows CE: Unsupported.
Header: Declared in msiquery.h.
Import Library: Use msi.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT.

See Also

Database Access Reference, User Interface Functions


MsiProcessMessage

The MsiProcessMessage function sends an error record to the installer for processing.

int MsiProcessMessage(
  MSIHANDLE hInstall,       // installer handle
  MSIMESSAGE eMessageType,  // type of message
  MISHANDLE hRecord         // record handle
);

Parameters

hInstall
Handle to the installation.
eMessageType
Specifies the message type. This parameter can be one of the following values.
Value | Meaning
MSIMESSAGE_OutOfMemory | The process is out of memory, may call recursively.
MSIMESSAGE_Error Error message,
[1] is message number in Error table.
MSIMESSAGE_Warning Warning message,
[1] is message number in Error table.
MSIMESSAGE_User User request,
[1] is message number in Error table.
MSIMESSAGE_Info Informative message for log,
not to be displayed.
MSIMESSAGE_Diagnostic Debug notification,
displayed only if no log.
MSIMESSAGE_CommonData Info for UI:
[1]=language ID,
[2]=dialog caption.
MSIMESSAGE_Reserved | Reserved for future use.
MSIMESSAGE_ActionStar Progress: start of action,
[1] action name,
[2] description.
MSIMESSAGE_ActionData | Progress: data associated with individual action item.
MSIMESSAGE_Progress Progress: gauge info,
[1] units so far,
[2] total.
MSIMESSAGE_ActionData Progress:
end of action sequence,
exit modeless dialog.

hRecord
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.

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.

QuickInfo

Windows NT: Requires version 4.0 or later. Available as a redistributable for Windows NT 4.0.
Windows: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Windows CE: Unsupported.
Header: Declared in msiquery.h.
Import Library: Use msi.lib.

See Also

Database Access Reference, Installer Action Functions


MsiRecordClearData

The MsiRecordClearData function sets all fields in a record to NULL.

unsigned int MsiRecordClearData(
  MSIHANDLE hRecord   // record handle
);

Parameters

hRecord
Handle to the record.

Return Values

ERROR_INVALID_HANDLE
The handle is inactive or does not represent a record.
ERROR_SUCCESS
The function succeeded.

QuickInfo

Windows NT: Requires version 4.0 or later. Available as a redistributable for Windows NT 4.0.
Windows: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Windows CE: Unsupported.
Header: Declared in msiquery.h.
Import Library: Use msi.lib.

See Also

Database Access Reference, Record Processing Functions


MsiRecordDataSize

The MsiRecordDataSize function returns the length of a record field.

unsigned int MsiRecordDataSize(
  MSIHANDLE hRecord,    // record handle
  unsigned int iField   // record field
);

Parameters

hRecord
Handle to the record.
iField
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.

QuickInfo

Windows NT: Requires version 4.0 or later. Available as a redistributable for Windows NT 4.0.
Windows: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Windows CE: Unsupported.
Header: Declared in msiquery.h.
Import Library: Use msi.lib.

See Also

Database Access Reference, Record Processing Functions


MsiRecordGetFieldCount

The MsiRecordGetFieldCount function returns the number of fields in a record.

unsigned int MsiRecordGetFieldCount(
  MSIHANDLE hRecord    // record handle
);

Parameters

hRecord
Handle to a record.

Return Values

If the function succeeds, the return value is the number of fields in the record.

If the function fails, the return value can be the following.

ERROR_INVALID_HANDLE
An invalid or inactive handle was supplied.

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.

QuickInfo

Windows NT: Requires version 4.0 or later. Available as a redistributable for Windows NT 4.0.
Windows: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Windows CE: Unsupported.
Header: Declared in msiquery.h.
Import Library: Use msi.lib.

See Also

Database Access Reference, 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
Handle to a record.
iField
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.

QuickInfo

Windows NT: Requires version 4.0 or later. Available as a redistributable for Windows NT 4.0.
Windows: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Windows CE: Unsupported.
Header: Declared in msiquery.h.
Import Library: Use msi.lib.

See Also

Database Access Reference, 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
Handle to the record.
iField
Specifies the field requested.
szValueBuf
Specifies a buffer to hold the returned string.
pcchValueBuf
Pointer to the size of the buffer.

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 from the MsiRecordGetString function, the pcchValueBuf parameter contains the size of the buffer required to hold the string. If ERROR_SUCCESS is returned, pcchValueBuf contains the number of characters written to the string buffer.

QuickInfo

Windows NT: Requires version 4.0 or later. Available as a redistributable for Windows NT 4.0.
Windows: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Windows CE: Unsupported.
Header: Declared in msiquery.h.
Import Library: Use msi.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT.

See Also

Database Access Reference, 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
Handle to the record.
iField
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.
TRUE
The function succeeded and the field is null.

Remarks

For the MsiRecordIsNull function, an integer value specifying a non-existent field of the record returns TRUE.

The iField parameter is based on 1.

QuickInfo

Windows NT: Requires version 4.0 or later. Available as a redistributable for Windows NT 4.0.
Windows: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Windows CE: Unsupported.
Header: Declared in msiquery.h.
Import Library: Use msi.lib.

See Also

Database Access Reference, Record Processing Functions


MsiRecordReadStream

The MsiRecordReadStream function reads bytes from a record stream field into a buffer.

UINT MsiRecordReadStream(
  MSIHANDLE hRecord,    // record handle
  unsigned int iField,  // field of record
  char *szDataBuf,      // buffer to receive bytes from stream
  DWORD *pchDataBuf     // in/out buffer count
);

Parameters

hRecord
Handle to the record.
iField
Specifies the field of the record.
szDataBuf
Specifies the buffer to hold data.
pchDataBuf
Specifies the in/out buffer count.

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

When using the MsiRecordReadStream function, you must set the pchDataBuf parameter to the requested byte count to read. The number of bytes transferred is returned through the pchDataBuf parameter. If no more bytes are available, ERROR_SUCCESS is still returned.

QuickInfo

Windows NT: Requires version 4.0 or later. Available as a redistributable for Windows NT 4.0.
Windows: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Windows CE: Unsupported.
Header: Declared in msiquery.h.
Import Library: Use msi.lib.

See Also

Database Access Reference, 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
Handle to the record.
iField
Specifies the field of the record to set.
iValue
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.

QuickInfo

Windows NT: Requires version 4.0 or later. Available as a redistributable for Windows NT 4.0.
Windows: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Windows CE: Unsupported.
Header: Declared in msiquery.h.
Import Library: Use msi.lib.

See Also

Database Access Reference, Record Processing Functions


MsiRecordSetStream

The MsiRecordSetStream function sets a record stream field from a file.

UINT MsiRecordSetStream(
  MSIHANDLE hRecord,      // record handle
  unsigned int iField,    // field of record
  LPCTSTR szFilePath      // path to file containing stream
);

Parameters

hRecord
Handle to the record.
iField
Specifies the field of the record to set.
szFilePath
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.

QuickInfo

Windows NT: Requires version 4.0 or later. Available as a redistributable for Windows NT 4.0.
Windows: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Windows CE: Unsupported.
Header: Declared in msiquery.h.
Import Library: Use msi.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT.

See Also

Database Access Reference, 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
Handle to the record.
iField
Specifies the field of the record to set.
szValue
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.

QuickInfo

Windows NT: Requires version 4.0 or later. Available as a redistributable for Windows NT 4.0.
Windows: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Windows CE: Unsupported.
Header: Declared in msiquery.h.
Import Library: Use msi.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT.

See Also

Database Access Reference, 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
Handle to the installation.
szTable
Specifies the name of the table containing the action sequence.
iSequenceMode
Specifies the sequence mode.

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.

QuickInfo

Windows NT: Requires version 4.0 or later. Available as a redistributable for Windows NT 4.0.
Windows: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Windows CE: Unsupported.
Header: Declared in msiquery.h.
Import Library: Use msi.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT.

See Also

Database Access Reference, 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
Handle to the installation.
szComponent
Specifies the name of the component.
iState
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_INVALID_HANDLE
An invalid or inactive handle was supplied.
ERROR_SUCCESS
The function succeeded.
ERROR_UNKNOWN_FEATURE
An unknown feature was requested.

Remarks

The MsiSetComponentState function requests a change in the Action state of a record in the Component table.

QuickInfo

Windows NT: Requires version 4.0 or later. Available as a redistributable for Windows NT 4.0.
Windows: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Windows CE: Unsupported.
Header: Declared in msiquery.h.
Import Library: Use msi.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT.

See Also

Database Access Reference, Installer Selection Functions


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
Handle to the installation.
szFeature
Specifies the name of the feature.
iState
Specifies the state to set. This parameter can be one of the following values.
Value | Meaning
INSTALLSTATE_ABSENT | The feature was uninstalled.
INSTALLSTATE_LOCAL | The feature was installed on the local drive.
INSTALLSTATE_SOURCE | The feature will run from source, CD, or network.

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.

QuickInfo

Windows NT: Requires version 4.0 or later. Available as a redistributable for Windows NT 4.0.
Windows: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Windows CE: Unsupported.
Header: Declared in msiquery.h.
Import Library: Use msi.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT.

See Also

Database Access Reference, 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
Handle to the installation.
iInstallLevel
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 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.

QuickInfo

Windows NT: Requires version 4.0 or later. Available as a redistributable for Windows NT 4.0.
Windows: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Windows CE: Unsupported.
Header: Declared in msiquery.h.
Import Library: Use msi.lib.

See Also

Database Access Reference, 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
Handle to the installer.
iRunMode
Specifies the run mode.
fState
Specifies the state to set. 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.

Return Values

ERROR_ACCESS_DENIED
Access was denied.
ERROR_INVALID_HANDLE
An invalid or inactive handle was supplied.
ERROR_SUCCESS
The function succeeded.

QuickInfo

Windows NT: Requires version 4.0 or later. Available as a redistributable for Windows NT 4.0.
Windows: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Windows CE: Unsupported.
Header: Declared in msiquery.h.
Import Library: Use msi.lib.

See Also

Database Access Reference, 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
Handle to the installer.
szName
Specifies the name of the property.
szValue
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.

QuickInfo

Windows NT: Requires version 4.0 or later. Available as a redistributable for Windows NT 4.0.
Windows: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Windows CE: Unsupported.
Header: Declared in msiquery.h.
Import Library: Use msi.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT.

See Also

Database Access Reference, 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
Handle to the installation.
szFolder
Specifies the folder identifier. This is a primary key in the Directory table.
szFolderPath
Specifies the full path for the folder, ending in a directory separator.

Return Values

ERROR_DIRECTORY
The target path could not be set.
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.

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.

QuickInfo

Windows NT: Requires version 4.0 or later. Available as a redistributable for Windows NT 4.0.
Windows: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Windows CE: Unsupported.
Header: Declared in msiquery.h.
Import Library: Use msi.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT.

See Also

Database Access Reference, 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
  LPCTSTR szValueBuf,       // value buffer
  DWORD *pcchValueBuf       // buffer size
);

Parameters

hSummaryInfo
Handle to summary information.
uiProperty
Specifies the property ID.
puiDataType
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
Specifies the returned integer property data.
pftValue
Pointer to a file value.
szValueBuf
Specifies the returned string property data.
pcchValueBuf
Specifies the size of the string buffer.

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.

QuickInfo

Windows NT: Requires version 4.0 or later. Available as a redistributable for Windows NT 4.0.
Windows: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Windows CE: Unsupported.
Header: Declared in msiquery.h.
Import Library: Use msi.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT.

See Also

Database Access Reference, 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
Handle to summary information.
puiPropertyCount
Specifies the location to which to return the total property count.

Return Values

ERROR_INVALID_HANDLE
An invalid or inactive handle was supplied.
ERROR_SUCCESS
The function succeeded.

QuickInfo

Windows NT: Requires version 4.0 or later. Available as a redistributable for Windows NT 4.0.
Windows: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Windows CE: Unsupported.
Header: Declared in msiquery.h.
Import Library: Use msi.lib.

See Also

Database Access Reference, 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
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.

QuickInfo

Windows NT: Requires version 4.0 or later. Available as a redistributable for Windows NT 4.0.
Windows: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Windows CE: Unsupported.
Header: Declared in msiquery.h.
Import Library: Use msi.lib.

See Also

Database Access Reference, 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
  LPCTSTR szValue         // text value, used only if string property
);

Parameters

hSummaryInfo
Handle to summary information.
uiProperty
Specifies the property to set.
uiDataType
Specifies the type of property to set.
iValue
Specifies the integer value.
pftValue
Specifies the file-time value.
szValue
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.

QuickInfo

Windows NT: Requires version 4.0 or later. Available as a redistributable for Windows NT 4.0.
Windows: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Windows CE: Unsupported.
Header: Declared in msiquery.h.
Import Library: Use msi.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT.

See Also

Database Access Reference, 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
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.

QuickInfo

Windows NT: Requires version 4.0 or later. Available as a redistributable for Windows NT 4.0.
Windows: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Windows CE: Unsupported.
Header: Declared in msiquery.h.
Import Library: Use msi.lib.

See Also

Database Access Reference, Installer Selection Functions


MsiViewClose

The MsiViewClose function releases the result set for an executed view.

UINT MsiViewClose(
  MSIHANDLE hView    // view handle
);

Parameters

hView
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.

QuickInfo

Windows NT: Requires version 4.0 or later. Available as a redistributable for Windows NT 4.0.
Windows: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Windows CE: Unsupported.
Header: Declared in msiquery.h.
Import Library: Use msi.lib.

See Also

Database Access Reference, General Database Access Functions


MsiViewExecute

The MsiViewExecute function executes the view query, supplying parameters as required.

UINT MsiViewExecute(
  MSIHANDLE hView,    // view handle
  MSIHANDLE hRecord   // parameter record
);

Parameters

hView
Handle to the view upon which to execute the query.
hRecord
Handle to a record that supplies parameters as required. This parameter contains values to replace parameter markers 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 in the predicate expression with parameter markers, a record with all replacement values in exact order and of compatible data types must be supplied.

QuickInfo

Windows NT: Requires version 4.0 or later. Available as a redistributable for Windows NT 4.0.
Windows: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Windows CE: Unsupported.
Header: Declared in msiquery.h.
Import Library: Use msi.lib.

See Also

Database Access Reference, General Database Access Functions


MsiViewFetch

The MsiViewFetch function fetches the next sequential record from the view.

UINT MsiViewFetch(
  MSIHANDLE hView,      // view handle
  MSIHANDLE *phRecord   // handle for fetched record
);

Parameters

hView
Handle to the view to fetch from.
phRecord
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.

QuickInfo

Windows NT: Requires version 4.0 or later. Available as a redistributable for Windows NT 4.0.
Windows: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Windows CE: Unsupported.
Header: Declared in msiquery.h.
Import Library: Use msi.lib.

See Also

Database Access Reference, General Database Access Functions


MsiViewGetColumnInfo

The MsiViewGetColumnInfo function returns a record containing column names or definitions.

UINT MsiViewGetColumnInfo(
 MSIHANDLE hView,         // view handle
 MSICOLINFO eColumnInfo,  // type of information to return, names
                          // or definitions
 MSIHANDLE *phRecord      // handle for returned record
);

Parameters

hView
Handle to the view from which to obtain column information.
eColumnInfo
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
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 MsiViewGetColumnInfo function uses the following column definition format.

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)

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.

QuickInfo

Windows NT: Requires version 4.0 or later. Available as a redistributable for Windows NT 4.0.
Windows: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Windows CE: Unsupported.
Header: Declared in msiquery.h.
Import 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
Handle to the view.
szColumnNameBuffer
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
Specifies the size of the buffer. This parameter returns the size required for the buffer if an error occurs.

Return Values

This function returns one of the following values.

Error code | Error number | Meaning
MSIDBERROR_INVALIDARG | -3 | An argument was invalid.
MSIDBERROR_MOREDATA | -2 | The buffer was too small to receive data.
MSIDBERROR_FUNCTIONERROR | -1 | The function failed.
MSIDBERROR_NOERROR | 0 | The function completed successfully with no errors.
MSIDBERROR_DUPLICATEKEY | 1 | The new record duplicates primary keys of the existing record in a table.
MSIDBERROR_REQUIRED | 2 | There are no NULL values allowed, or the column is about to be deleted but is referenced by another row.
MSIDBERROR_BADLINK | 3 | The corresponding record in a foreign table was not found.
MSIDBERROR_OVERFLOW | 4 | The data is greater than the maximum value allowed.
MSIDBERROR_UNDERFLOW | 5 | The data is less than the minimum value allowed.
MSIDBERROR_NOTINSET | 6 | The data is not a member of the values permitted in the set.
MSIDBERROR_BADVERSION | 7 | An invalid version string was supplied.
MSIDBERROR_BADCASE | 8 | The case was invalid. The case must be all uppercase or all lowercase.
MSIDBERROR_BADGUID | 9 | An invalid GUID was supplied.
MSIDBERROR_BADWILDCARD | 10 | An invalid wildcard file name was supplied, or the use of wildcards was invalid.
MSIDBERROR_BADIDENTIFIER | 11 | An invalid identifier was supplied.
MSIDBERROR_BADLANGUAGE | 12 | Invalid language IDs were supplied.
MSIDBERROR_BADFILENAME | 13 | An invalid file name was supplied.
MSIDBERROR_BADPATH | 14 | An invalid path was supplied.
MSIDBERROR_BADCONDITION | 15 | An invalid conditional statement was supplied.
MSIDBERROR_BADFORMATTED | 16 | An invalid format string was supplied.
MSIDBERROR_BADTEMPLATE | 17 | An invalid template string was supplied.
MSIDBERROR_BADDEFAULTDIR | 18 | An invalid string was supplied in the DefaultDir column of the Directory table.
MSIDBERROR_BADREGPATH | 19 | An invalid registry path string was supplied.
MSIDBERROR_BADCUSTOMSOURCE | 20 | An invalid string was supplied in the CustomSource column of the CustomAction table.
MSIDBERROR_BADPROPERTY | 21 | An invalid property string was supplied.
MSIDBERROR_MISSINGDATA | 22 | The _Validation table is missing a reference to a column.
MSIDBERROR_BADCATEGORY | 23 | The category column of the _Validation table for the column is invalid.
MSIDBERROR_BADCABINET | 24 | An invalid cabinet name was supplied.
MSIDBERROR_BADKEYTABLE | 25 | The table in the Keytable column of the _Validation table was not found or loaded.
MSIDBERROR_BADMAXMINVALUES | 26 | The value in the MaxValue column of the _Validation table is less than the value in the MinValue column.
MSIDBERROR_BADSHORTCUT | 27 | An invalid shortcut target name was supplied.
MSIDBERROR_STRINGOVERFLOW | 28 | The string is too long for the length specified by the column definition.
MSIDBERROR_BADLOCALIZEATTRIB | 29 | 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.

QuickInfo

Windows NT: Requires version 4.0 or later. Available as a redistributable for Windows NT 4.0.
Windows: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Windows CE: Unsupported.
Header: Declared in msiquery.h.
Import Library: Use msi.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT.

See Also

Database Access Reference, 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
Handle to a view.
eModifyMode
Specifies the modify mode. This parameter can be one of the following values.
Value | Meaning
MSIMODIFY_REFRESH | Refetch current record data.
MSIMODIFY_INSERT | Insert a new record. The function fails if a matching key exists.
MSIMODIFY_UPDATE | Update the existing non-key data of the fetched record.
MSIMODIFY_ASSIGN | Insert a new record. If a matching key exists, the record is replaced.
MSIMODIFY_REPLACE | Update the record, delete the old if primary key edit.
MSIMODIFY_MERGE | The function fails if there is a record with a duplicate key that is not identical.
MSIMODIFY_DELETE | Remove a row referenced by this record from the table.
MSIMODIFY_INSERT_TEMPORARY | Insert a temporary record.
MSIMODIFY_VALIDATE | Validate a fetched record.
MSIMODIFY_VALIDATE_DELETE | Validate a record to be deleted.
MSIMODIFY_VALIDATE_NEW | Validate a new record.
MSIMODIFY_VALIDATE_FIELD | Validate field(s) of an incomplete record.

hRecord
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, and MSIMODIFY_VALIDATE_FIELD values of the MsiViewModify function do not perform actual updates; they ensure that the data in the record is valid.

The MsiViewModify function uses the following action and modification mode descriptions.

MSIMODIFY_INSERT
Inserts the information into the database table. You are not required to call the MsiViewFetch function before you call this operation. MsiViewModify fails if a row with the same primary keys exists in the table. For this operation, the database must be writable.
MSIMODIFY_UPDATE
Updates the existing information in the database, allowing modification of non-primary keys only. Before you call this operation, you must call the MsiViewFetch function with the same record as that returned by the fetch. The function fails if the row has been deleted from the table. For this operation, the database must be writable.
MSIMODIFY_DELETE
Deletes the information already existing in the database. Before you call this operation, you must call the MsiViewFetch function with the same record as that returned by the fetch. The function fails if the row has been deleted from the table. For this operation, the database must be writable.
MSIMODIFY_INSERT_TEMPORARY
Temporarily inserts the information into the database table. The information is not persistent. You are not required to call the MsiViewFetch function before you call this operation. The function fails if a row with the same primary keys exists. For this operation, the database can be writable or read-only.
MSIMODIFY_REFRESH
Refreshes the information in the record from the database. Before you call this operation, you must call the MsiViewFetch function with the same record as that returned by the retrieval. The function fails if the row has been deleted from the table. For this operation, the database can be writable or read-only.
MSIMODIFY_ASSIGN
Inserts or updates the information into the database table. You are not required to call the MsiViewFetch function before you call this operation. An update operation takes place if primary keys match an existing row. An insert operation takes place if primary keys do not match any row. In either case, the current data in the cursor is written to a table row. For this operation, the database must be writable.
MSIMODIFY_MERGE
Inserts or validates the information into the database table. You are not required to call the MsiViewFetch function before you call this operation. An insert operation takes place if primary keys do not match any row. A validation operation takes place if primary keys match an existing row. The operation fails if the record data does not match the data in the table. For this operation, the database must be writable.
MSIMODIFY_REPLACE
Performs an update or a delete/insert operation on the information that is going into the database table. Before you call this operation, you must call the MsiViewFetch function with the same record as that returned by the fetch. If the primary keys have not been changed, an update of the table row occurs. If the primary keys have been changed, the old table row is deleted and a new row corresponding to the record is inserted. For this operation, the database must be writable.
MSIMODIFY_VALIDATE
Validates a record. This operation does not validate across joins. Before calling the operation, you must call the MsiViewFetch function with the same record as that returned by the fetch. You can obtain validation errors by calling MsiViewGetError. For this operation, the database can be read-only or writable.
MSIMODIFY_VALIDATE_DELETE
Validates a row of a retrieved record that will later be deleted. Before calling this operation, you must call the MsiViewFetch function. The function fails if another row of a table refers to the primary keys of this row. However, validation does not check for the existence of the primary keys of this row in properties or strings. This operation also does not check if a column might be a foreign key to possibly multiple tables of which the table for this row is listed. You can obtain validation errors by calling MsiViewGetError.
MSIMODIFY_VALIDATE_NEW
Validates a record as a new record. This operation does not validate across joins. This operation differs from MSIMODIFY_VALIDATE because it checks for duplicate keys. You can obtain validation errors by calling MsiViewGetError. For this operation, the database must be writable.
MSIMODIFY_VALIDATE_FIELD
Validates fields of a fetched or new record. This operation does not validate across joins. The validation depends upon the number of fields in the record. If only one field exists, the operation validates only that field. The operation can also validate more fields. It should be used when the fetched/new record does not represent every column of the table. You can obtain validation errors by calling MsiViewGetError. For this operation, the database can be writable or read-only.

QuickInfo

Windows NT: Requires version 4.0 or later. Available as a redistributable for Windows NT 4.0.
Windows: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Windows CE: Unsupported.
Header: Declared in msiquery.h.
Import Library: Use msi.lib.

See Also

Database Access Reference, General Database Access Functions


User Interface

This section describes the user interface portion of the Microsoft® Windows® installer. You can author a full graphical user interface by populating the appropriate tables or you can choose to bypass the internal UI functionality and use an external UI.


About The User Interface

You can author a full graphical user interface from within the Microsoft® Windows® installer. To use the interface you must populate the appropriate tables. For each dialog box that you want to use, you must enter its properties in the Dialog table. Similarly, the BillBoard table is for the billboards you can display. You can fill dialog boxes and billboards with controls by populating the Control table and BBControl table, respectively. You may need to present a different set of controls based on various conditions. There may be a control that should be presented if the operating system is Microsoft® Windows NT® but not if it is Microsoft® Windows® 95. You can set whether a control is presented based on a conditional expression with the ControlCondition table.

There are many events that controls on a dialog box can both broadcast and respond to. The logic of what happens is defined within the ControlEvent table and the EventMapping table. The EventMapping table indicates the controls that should respond to events while the ControlEvent table describes the events that are broadcast by a control. For more information about control events see ControlEvent overview.

Some controls have more information associated with them. You can use check boxes in your user interface by filling the CheckBox table with the appropriate values. Use a check box to allow the user to set a property to some value. The records in the check box table are linked to the control table by the property that the control sets. A similar method of setting properties can also be used with other controls such as combo boxes, list boxes, radio buttons, and list views. The information for these controls is contained in the ComboBox table, the ListBox table, the RadioButton table, and the ListView table, respectively.

There are several tables relating to the text you might need to use during an installation. You can make your dialog box present information to the user or write it to a log in response to installation actions by populating the ActionText table. The UIText table contains the text that is presented to the user. You can define a set of styles for text formatting by populating the TextStyle table. If this table is populated, you can refer to the styles to format strings in other tables.


User Interface Schema


Control Overview

The controls are divided into two major groups: active and inert. The active controls are linked to some property. These controls are authored with some property. When the control is created it shows the initial value of the property. The user can change the value of the property by interacting with the control. The inert controls are not linked to a property; they do not change a property value.


ControlEvent Overview

Controls on the same dialog box can communicate with each other by means of ControlEvents.

Each ControlEvent has one publisher (a control or the installer itself) and can have several subscribers. The kind of ControlEvents published by a control is determined by the type of the control. Theoretically any control can subscribe to any ControlEvent, although many combinations are not practical.

A control can subscribe to a ControlEvent in the following ways:

  • If a control is listed in the EventMapping table with a ControlEvent, it describes the attribute of the control that must be changed when the ControlEvent is published.
  • If a control is listed in the ControlEvent table with a ControlEvent, it means that activating the control (clicking the button) triggers a ControlEvent with the described parameter.

A custom control can publish its own ControlEvents and other controls (custom or regular) can subscribe to them.

The publisher of a ControlEvent can hide/show or enable/disable its subscribers when its state requires it.

It is perfectly reasonable to have a control on a dialog box that publishes some ControlEvent but to have no subscribers to the control. In contrast, if a control subscribes to a ControlEvent that is not published by the handler and a publishing control is not present on the same dialog box, it can result in an error (especially if the control attempts to trigger that event).

For a more comprehensive explanation on a specific control, see the ControlEvents list.


Progress Bar Overview

During script execution time, you can display a progress bar representing the status (time elapsed relative to time remaining) of the installation. In addition, the approximate time remaining for the install can also be displayed (in minutes and seconds).

Here is an overview on how progress bars work in installer.

  • While generating an execution script, MsiEngine keeps track of the total progress ticks anticipated by each action (it does this by intercepting ixoProgressTotal script records, and tallying up the specified tick counts). At the end of script generation, the grand tick total is stored as the last field of the ixoEnd record.
  • Once the script starts executing, the ixoHeader execution action seeks to the end of the script, pulls out the progress tick total, and sends a "progress master reset" message via the standard Message function. When the active message handler (either MsiHandler, or the Basic UI message object if no MsiHandler is active) receives this message, it resets its internal progress state, and stores away the progress tick total.
  • As each script record is executed, progress messages are sent to the active message handler, each detailing the elapsed number of progress ticks. On each progress message, the MsiHandler (if active) broadcasts a SetProgress ControlEvent to the active dialog (assumed in our discussion to be a modeless dialog, with a ProgressBar control somewhere on it).
  • The active dialog receiving the SetProgress event checks the EventMapping table for any controls subscribing to that event. In this case, the ProgressBar on the dialog should be a subscriber, with the "Progress" attribute specified in the Attributes column. If so, the "Progress" attribute of the ProgressBar will be set with the "ticksSoFar" and "totalTicks" values passed along with the SetProgress ControlEvent, and the progress bar advances (all other control types ignore the Progress attribute).
  • In addition, on each progress message, the MsiHandler also broadcasts a TimeRemaining ControlEvent. The total time remaining for the install is determined by first determining the dynamic "execution rate", i.e. the total number of ticks elapsed divided by the total time since the "master reset" message. The total ticks remaining divided by the execution rate gives the approximate time remaining.
  • When receiving the TimeRemaining ControlEvent, the active dialog again looks in the EventMapping table, this time for any TimeRemaining subscribers. In order to display the time remaining, a Text control should be a subscriber, with the "TimeRemaining" attribute specified in the Attributes column. If so, the "TimeRemaining" attribute of the Text control will be set with the time remaining, in seconds. When this attribute is set on a Text control, that control will automatically look in the UIText table for a parameterized template string named "TimeRemaining". This string should have two parameters, [1] for minutes, and [2] for seconds. A good example for this string would be:
  • "Time remaining: {[1] min }[2] sec" (The curly braces specify that if the minutes parameter drops to zero, only the seconds portion will be displayed).
  • The Text control then converts the total seconds value to minutes and seconds, inserts these values into the TimeRemaining template string, and displays it. (If the template string is not found in the UIText table, you'll only get "UIText string not found!" message).
  • If the Basic UI message handler is active (for example, if "LIMITUI=1" is specified as a property on the command line), the progress bar and "Time Remaining" text field are built in to the basic dialog.


Using The User Interface

There are many dialog boxes you can author for your installation. To author a dialog box, you must populate the various tables. For examples of common dialog boxes and how to author dialog boxes in the Microsoft® Windows® installer database, see User Interface.


FilesInUse Dialog

This dialog box can be authored to inform the user of any processes that are using files that must be overwritten or deleted. This gives the user the opportunity to shut down the offending processes, thus avoiding the necessity of rebooting the computer to complete the replacement or deletion of the in-use files. This dialog box is created as required by the InstallValidate action. See that topic for complete details.


FirstRun Dialog

The FirstRun Dialog opens a user interface wizard that collects the user name, company name, and product ID information. The installer will also verify the product ID during this dialog. The FirstRun Dialog is typically 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 or create a different dialog sequence. The dialog sequence however needs to have the user set the USERNAME property, COMPANYNAME property, and 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.


Browse Dialog

You can use this dialog box to select a directory, though the directory does not have to exist.

The dialog box typically contains the following controls:

  • 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.

The preceding three controls are connected to the same property (possibly indirectly). The property is the path being selected.

The DirectoryCombo control specifies, with its stylebits, the volume types that are displayed. On a typical Browse dialog box, probably all types should be turned on.

The dialog box typically also contains three PushButton controls, that serve as Up One Level, New Folder, and Open buttons. The buttons subscribe to the DirectoryListUp, DirectoryListNew, and DirectoryListOpen control events respectively, using the ControlEvent Table.

If the dialog box is designed to search for existing folders only, the New Folder button can be omitted.

When this dialog box is authored, the "NewFolder" string must be defined in the UIText Table.


Cancel Dialog

You can use this modal dialog box to confirm that the user wants to terminate the installation. This dialog box typically contains a Text control and two PushButtons. The two buttons give the user the choice to return to the last dialog box or confirm the termination of the installation. The two buttons in the ControlEvent Table are linked to the EndDialog control event with the Return and Exit parameters. The Return parameter causes the Cancel dialog box to be terminated and the focus returns to the previous dialog box. The Exit parameter 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

This dialog box typically appears when the OutOfDiskSpace property is set indicating that there is not enough disk space for the currently selected installation.

This dialog box or a variation of it can also be activated from the Selection Dialog, to give the user an overview of the disk space needed on the different volumes.

The dialog box is modal and normally contains a VolumeCostList control and a PushButton that returns the user to the previous dialog box. It can contain other controls like static text or pictures.


Error Dialog

You can use this modal dialog box to display an error message. More than one error dialog box is possible in one installation. The ErrorDialog property specifies which dialog box is used as an error dialog box. If this property is not set or does not point to a valid error dialog box, the error messages are not displayed, only logged with a warning about the missing error dialog box.

This dialog box must have the ErrorDialog style bit set. The dialog box must have a Text control named ErrorText. This control displays the text of the error message.

The dialog box is also authored with seven PushButtons. These buttons must specify the EndDialog control event in the ControlEvent Table with the following parameters: ErrorAbort, ErrorCancel, ErrorIgnore, ErrorNo, ErrorOk, ErrorRetry, ErrorYes.

You should author the buttons in approximately the same position. When the dialog box is created only a subset of these buttons is created, depending on the message, and the X coordinate of the buttons is modified so the displayed buttons are evenly spaced. The other three coordinates of the buttons are not changed. Since the buttons are rearranged, the author should make sure that no other control is placed in the same horizontal region of the dialog box as the buttons.

The error message can consist of three portions. The first portion is the text of the error message, and it is required.

The second portion is a list of letters, enclosed in curly braces, specifying the buttons to create. The letters are the first letters of the words abort, cancel, ignore, no, Ok, retry, 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 default.

The third portion of the error message is optional. If present, this string is used as the title for the dialog box, overwriting the title entered in the Dialog Table. If this string is present the second portion must also be present to separate the part. (remember, the second part can be an empty list {}).

For an error dialog box, the FirstControl, DefaultControl, and CancelControl entries in the Dialog Table are ignored, and the default button specified by the message plays all three roles.


Exit Dialog

This modal dialog box displays 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.


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.


LicenseAgreement Dialog

This modal dialog box displays the license agreement to the user. Typically the text of the agreement is displayed in a ScrollableText control.

The dialog box typically also contains a pair of option buttons that let the user accept or reject the agreement. For legal reasons it is advisable that neither of the buttons is selected initially, forcing the user to make an active choice. This can be achieved by not having an initial value for the property linked to the RadioButtonGroup. The author can also disable/enable the next button on this dialog box, depending on the choice made. Another possible situation is when the next button takes the user to different dialog boxes depending on the choice he or she makes.


Selection Dialog

This modal dialog box enables the user to select individual items. The dialog box contains a SelectionTree control that displays the main information. This control publishes several events that change the display on other controls of the dialog box. Typically there are four Text controls subscribing to the SelectionAction, SelectionDescription, SelectionSize, and SelectionPath events using the Text control attribute. There is also a control that subscribes to the SelectionIcon event through the ImageHandle attribute. The above controls use the EventMapping Table to specify these subscriptions. There is also a PushButton that subscribes to the SelectionBrowse event using the ControlEvent Table and giving the name of the Browse dialog as the parameter. When a SelectionTree control is authored, the AbsentPath, SelAbsentAbsent, SelAbsentLocal, SelAbsentCD, SelAbsentNetwork, SelLocalAbsent, SelLocalLocal, SelLocalCD, SelLocalNetwork, SelCDAbsent, SelNetworkAbsent, SelCDLocal, SelNetworkLocal, SelCDCD, SelNetworkNetwork, SelChildCostPos, SelChildCostNeg, SelParentCostPosPos, SelParentCostPosNeg, SelParentCostNegPos, SelParentCostNegNeg, MenuAbsent, MenuLocal, MenuCD, MenuNetwork strings must be specified in the UIText table. The selection tree gets populated only if the CostInitialize and CostFinalize actions were all previously called.


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.


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 1329 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.


Dialog for Suspending the Rollback of Failed Installs

To display a dialog box presenting the option to suspend the automatic rollback of a failed or cancelled installation
  1. Use the authoring capabilities of the installer to set the ALLOWSUSPEND property.
  2. Following a failed or cancelled installation, and before the final exit dialog, the installer will display a error dialog box giving the option of suspending the automatic rollback of a failed or cancelled install.
  3. Selecting to suspend the rollback in this dialog allows the pending installation to be continued at a later time. Rejecting to suspend rollback results in a rollback of the pending installation.
  4. When continuing the suspended install at a later time, you must use a command line that is identical to the command line of the first install.

The default for not setting the ALLOWSUSPEND property is to not display the dialog box and to continue with an automatic rollback of a failed or cancelled installation.


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 pushbutton 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 pushes 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 pushbutton control to this dialog, labeled Cancel, by authoring it into the Control table.
  3. Link the Cancel pushbutton 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 pushbutton 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.


User Interface Reference

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 on the installer, see About Windows Installer.

Dialog Stylebits List

The following list provides links to more information about dialog box stylebits:

Error = 65536 (0x00010000)
KeepModeless = 16 (0x00000010)
Minimize = 4 (0x00000004)
Modal = 2 (0x00000002)
TrackDiskSpace = 32 (0x00000020)
UseCustomPalette = 64 (0x000040)
Visible = 1 (0x00000001)

Controls List

The following list provides links to more information about inert controls:

Billboard
Bitmap
GroupBox
Icon
Line
ProgressBar Control
PushButton
ScrollableText
Text
VolumeCostList

The following list provides links to more information about active controls:

CheckBox
ComboBox
DirectoryCombo
DirectoryList
Edit
ListBox
ListView
MaskedEdit
PathEdit
RadioButtonGroup
SelectionTree
VolumeSelectCombo

Control Attributes List

The following list provides links to more information about control attributes:

BillboardName
Default
Enabled
Image
ImageHandle
Indirect
IndirectPropertyName
Position
Progress
PropertyName
PropertyValue
Text
Transparent
Visible
WindowHandle

When a control is created several attributes can be selected by setting certain style bits.

Control Stylebits List

The following list provides links to more information about control stylebits:

Bitmap = 262144 (0x00040000)
CDROMVolume = 524288 (0x00080000)
ComboList = 131072 (0x00020000)
Enabled = 2 (0x00000002)
FixedSize = 1048576 (0x00100000)
FixedVolume = 131072 (0x00020000)
FloppyVolume = 2097152 (0x00200000)
HasBorder = 16777216 (0x01000000)
Icon = 524288 (0x00080000)
IconSize = 2097152 (0x00200000), 4194304 (0x00400000)
ImageHandle = 65536 (0x00010000)
Indirect = 8 (0x00000008)
Integer = 16 (0x00000010)
Progress95 = 65536 (0x00010000)
PushLike = 131072 (0x00020000)
RAMDiskVolume = 1048576 (0x00100000)
RemoteVolume = 262144 (0x00040000)
RemovableVolume = 65536 (0x00010000)
Sorted = 65536 (0x00010000)
Sunken = 4 (0x00000004)
Transparent = 65536 (0x00010000)
Visible = 1 (0x00000001)

ControlEvents List

The following list provides links to more information about ControlEvents:

ActionData
ActionText
AddLocal
AddSource
CheckExistingTargetPath
CheckTargetPath
DirectoryListNew
DirectoryListOpen ControlEvent
DirectoryListUp
DoAction
EndDialog
IgnoreChange
NewDialog
Reinstall
ReinstallMode
Remove
Reset
SelectionAction
SelectionBrowse
SelectionDescription
SelectionIcon
SelectionPath
SelectionPathOn
SelectionSize
SetInstallLevel
SetProgress
SetProperty
SetTargetPath
SpawnDialog
SpawnWaitDialog
TimeRemaining
ValidateProductID


Dialog Stylebits

This section describes dialog stylebits.


Error Dialog Stylebit

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.

Numeric Value

0x00010000 = 65536


KeepModeless Dialog Stylebit

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.

Numeric Value

0x00000010 = 16


Minimize Dialog Stylebit

If this bit is set, the dialog can be minimized. In Windows, the dialog's minimize button is enabled and the minimize item is enabled in the system menu. This bit is ignored for modeless dialogs that cannot be minimized.

Numeric Value

0x00000004 = 4


Modal Dialog Stylebit

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.

Numeric Value

0x00000002 = 2


TrackDiskSpace Dialog Stylebit

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/removes files or otherwise modifies the available disk space, you can quickly catch the change using this style.

Numeric Value

0x0000020 = 32


UseCustomPalette Dialog Stylebit

If this bit is set the pictures on the dialog will be 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 will be most likely to give a satisfactory result for all pictures.

Numeric Value

0x00000040 = 64


Visible Dialog Stylebit

If this bit is set the dialog is originally created as visible, otherwise it is hidden.

Numeric Value

0x0000001 = 1


Controls

This section describes controls.


Billboard Control

This control plays the billboards based on progress messages. The billboards are composed of individual controls that are added and later removed from the dialog.

Property

There can be no property associated with this control.

Valid Style Bits

None.

Valid Control Attributes

BillboardName
Position
Text
Visible
WindowHandle

Control Events Published

None.

Can Take Focus

No.

Remarks

This control has no window of its own.


Bitmap Control

This control simply displays a static picture of a bitmap.

Property

There can be no property associated with this control.

Valid Style Bits

FixedSize
ImageHandle
Visible

Valid Control Attributes

Default
Image
ImageHandle
Position
Text
Visible
WindowHandle

Control Events Published

None.

Can Take Focus

No.

Remarks

This control is created as a "STATIC" with the SS_BITMAP, SS_CENTERIMAGE, WS_CHILD, and WS_GROUP styles.


GroupBox Control

This control displays a rectangle, possibly with some caption. It only serves as a visual element on the dialog to group other controls together.

Because of the way Windows draws this control, there is a gap between the top of the control's window and the visible frame, even when there is no caption.

Property

There can be no property associated with this control.

Valid Style Bits

Visible

Valid Control Attributes

Default
Position
Text
Visible
WindowHandle

Control Events Published

None.

Can Take Focus

No.

Remarks

The control is created as a "BUTTON" with the BS_GROUPBOX, WS_CHILD, WS_GROUP styles.


Icon Control

This control simply displays a static picture of an icon. The background of the image is transparent.

An icon file can contain different size images of the same icon. If the IconSize bits are set, the first image of the specified size is loaded. If no size is specified, the first image is loaded.

If the IconSize bits are not set the FixedSize bit is ignored and the image is stretched to fit the control rectangle.

If both the IconSize bits and the FixedSize bit are set and the control is larger than the icon, the image is centered in the control. If the image is larger than the control it is not chopped (unlike in the Bitmap control) but shrunk to fit the control.

Property

There can be no property associated with this control.

Valid Style Bits

FixedSize
IconSize
ImageHandle
Visible

Valid Control Attributes

Default
Image
ImageHandle
Position
Text
Visible
WindowHandle

Control Events Published

None.

Can Take Focus

No.

No.

Remarks

This control is created as a "STATIC" with the SS_ICON, SS_CENTERIMAGE, WS_CHILD, and WS_GROUP styles.


Line Control

This is a simple horizontal line.

Property

There can be no property associated with this control.

Valid Style Bits

Visible

Valid Control Attributes

Default
Position
Text
Visible
WindowHandle

Control Events Published

None.

Can Take Focus

No.

Remarks

The Line control is implemented is using a STATIC control with the SS_ETCHEDHORZ and SS_SUNKEN styles.


ProgressBar Control

This control displays a rectangle filling up as it receives progress messages. Typically should subscribe to the SetProgress control event or a control event whose name matches the name of the action whose progress is gauged.

Property

There can be no property associated with this control.

Valid Style Bits

Progress95
Sunken
Visible

Valid Control Attributes

Default
Position
Progress
Text
Visible
WindowHandle

Control Events Published

None.

Can Take Focus

No.

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.

If the Bitmap or the Icon style bit is set, the corresponding text entry in the Control Table is taken as a foreign key to the Binary Table that specifies the binary data needed to create the picture.

This means that the button cannot have both a picture and a text.

Property

There can be no property associated with this control.

Valid Style Bits

Bitmap
Enabled
FixedSize
Icon
IconSize
ImageHandle
Sunken
Visible

Valid Control Attributes

Default
Enabled
Position
Text
Visible
WindowHandle

Control Events Published

None.

Can Take Focus

Yes.

Remarks

The control is created with the "BUTTON" class.

It has the BS_MULTILINE, WS_CHILD, WS_TABSTOP, WS_GROUP styles.

If the Bitmap style is set it has the BS_BITMAP style.

If the Icon style is set it has the BS_ICON style.


ScrollableText Control

This control displays a long text that cannot fit on a page normally. A typical application for this control is displaying the license agreement.

Property

There can be no property associated with this control.

Valid Style Bits

Enabled
Sunken
Visible

Valid Control Attributes

Enabled
Position
Text
Visible
WindowHandle

Control Events Published

None.

Can Take Focus

No.

Remarks

The control is created using the "RICHEDIT" class with the ES_MULTILINE, WS_HSCROLL, WS_VSCROLL, ES_READONLY, WS_TABSTOP, ES_AUTOHSCROLL, ES_AUTOVSCROLL, WS_CHILD and WS_GROUP styles.


Text Control

This control displays a static text. The text may use a predefined style. This is done by putting the name of the style in the form {\style} at the start of the string, where style is one of the keys in the TextStyle Table. A base text style can be assigned to the control by supplying {&style} at the very beginning of a the text string. This style is used whenever no other style is defined by the string.

Property

There can be no property associated with this control.

Valid Style Bits

Sunken
Transparent
Visible

Valid Control Attributes

Default
Enabled
Position
Text
Transparent
Visible
WindowHandle

Control Events Published

None.

Can Take Focus

No.

Remarks

The control is created with the "STATIC" class and with the SS_LEFT, WS_CHILD, WS_GROUP styles.

If the Transparent style is set the control also has the WS_EX_TRANSPARENT style.


VolumeCostList Control

This special control presents information to the user 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 available amount on some drive, the volume is highlighted in the table. Clicking on a column header sorts the volumes according to the chosen column.

Property

There can be no property associated with this control.

Valid Style Bits

CDROMVolume
Enabled
FixedVolume
FloppyVolume
RAMDiskVolume
RemoteVolume
RemovableVolume
Sunken
Visible

Valid Control Attributes

Enabled
Position
Text
Visible
WindowHandle

Control Events Published

None.

Can Take Focus

No.

Related Strings in the UIText Table

The strings for the column headings in the table:

VolumeCostAvailable
VolumeCostDifference
VolumeCostRequired
VolumeCostSize
VolumeCostVolume

The following four localized strings are used in formatting the size of a file.

Bytes
KB
MB
GB

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.


CheckBox Control

This control is a simple two-state check box. If the CheckBox table exists and specifies a value for the property associated with the checkbox, the property is set to this value when the checkbox is on, to null otherwise. If there is no such table, or it does not specify a value for this property, but the associated property has an initial value, the control remembers it and initially drawn as selected. When the control is unchecked, the property is set to NULL. If the check box is rechecked, it returns to its original value. If the property does not have an original value, it is set to "1" when the control is checked.

Property

The property associated with this control can be integer or string valued.

Valid Style Bits

Bitmap
Enabled
FixedSize
Icon
IconSize
ImageHandle
Indirect
Integer
PushLike
Sunken
Visible

Valid Control Attributes

Default
Enabled
Indirect
IndirectPropertyName
Position
PropertyName
PropertyValue
Text
Visible
WindowHandle

Control Events Published

None.

Can Take Focus

Yes.

Remarks

The control is created with the "BUTTON" class.

It has the BS_CHECKBOX, WS_TABSTOP, WS_GROUP, WS_CHILD and BS_MULTILINE styles.

If the PushLike style is set it has the BS_PUSHLIKE style.

If the Bitmap style is set it has the BS_BITMAP style.

If the Icon style is set it has the BS_ICON style.


ComboBox Control

This control is a drop-down combo box with an edit field. It makes a predefined list of values and also allows for the user to enter some new value. It reads the possible values from the ComboBox Table. If the sorted style is set, the items are displayed according the Ordering column of the table. If the style is not set, that column is ignored and the items are displayed in alphabetical order.

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.

Property

The property associated with this control can be integer or string valued.

Valid Style Bits

ComboList
Enabled
Indirect
Integer
Sorted
Sunken
Visible

Valid Control Attributes

Default
Enabled
Indirect
IndirectPropertyName
Position
PropertyName
PropertyValue
Text
Visible
WindowHandle

Control Events Published

None.

Can Take Focus

Windows: Yes.

Remarks

The control is created with the "COMBOBOX" class with the CBS_AUTOHSCROLL, WS_TABSTOP, WS_GROUP, WS_CHILD styles. If the ComboList style bit is on, it also has the CBS_DROPDOWNLIST style, otherwise it has the CBS_DROPDOWN style.

If the Sorted style is set, it also has the CBS_SORT style.

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

This is a special control designed for use on a browse dialog. It is designed to be used with a PathEdit control and a DirectoryList control on the same dialog. It lets the user select the main part of a path (everything except the last segment). It displays the available volumes in an alphabetical order and the steps of the currently displayed path in a hierarchical way. If the main part of the currently selected path contains any folders that do not exist, those files are displayed with a different icon. The property associated with this control has to have an initial value, and this value has to contain at least two steps (a volume and at least one level below). The selection of the initial style bits determines what kind of volumes are listed.

Property

The property associated with this control can be only string valued.

Valid Style Bits

CDROMVolume
Enabled
FixedVolume
FloppyVolume
Indirect
RAMDiskVolume
RemoteVolume
RemovableVolume
Sunken
Visible

Valid Control Attributes

Default
Enabled
Indirect
IndirectPropertyName
Position
PropertyName
PropertyValue
Text
Visible
WindowHandle

Control Events Published

None.

Can Take Focus

Windows: Yes.

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

This is a special control designed for use on a browse dialog. It is designed to be used with a PathEdit and DirectoryCombo control on the same dialog. It shows the user the folders below the main part of a path (everything except the last segment). It displays the folders below the main part of the currently selected path. If the list contains any folders that don't exist at present time, those are displayed with a different icon. The property associated with this control has to have an initial value, and this value has to contain at least two steps (a volume and at least one level below). The primary goal of this control is to let the user select a subfolder of the current selection. With some 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.

Property

The property associated with this control can be only string valued.

Valid Style Bits

Enabled
Indirect
Sunken
Visible

Valid Control Attributes

Default
Enabled
Indirect
IndirectPropertyName
Position
PropertyName
PropertyValue
Text
Visible
WindowHandle

Control Events Published

DirectoryListNew
IgnoreChange
DirectoryListUp
DirectoryListOpen

Can Take Focus

Windows: Yes.

Related Strings in the UIText Table

NewFolder The default name of a newly created folder.

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.


Edit Control

This is a regular edit field. The user can enter any string or integer. If the associated property is integer-valued it accepts only integer entries (not yet implemented). 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.

Property

The property associated with this control can be string or integer valued.

Valid Style Bits

Enabled
Indirect
Integer
Sunken
Visible

Valid Control Attributes

Default
Enabled
Indirect
IndirectPropertyName
Position
PropertyName
PropertyValue
Text
Visible
WindowHandle

Control Events Published

None.

Can Take Focus

Yes.

Remarks

The control is created with the "EDIT" class with the WS_BORDER, WS_CHILD, WS_TABSTOP, WS_GROUP styles.

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.


ListBox Control

This is a regular listbox control. It enables the user to select a value of a property from a pre-authored list of choices. This control supports only single select listboxes. The possible values are read from the Listbox Table. Note that the string displayed is not necessarily the same as the value that the user is choosing. If the control is created with the Sorted, the items are listed according to the Ordering column of the table. If the style bit is not set, the column is ignored.

Property

The property associated with this control can be string or integer valued.

Valid Style Bits

Enabled
Indirect
Integer
Sorted
Sunken
Visible

Valid Control Attributes

Default
Enabled
Indirect
IndirectPropertyName
Position
PropertyName
PropertyValue
Text
Visible
WindowHandle

Control Events Published

None.

Can Take Focus

Yes.

Remarks

The control is created with the "LISTBOX" class.

If the Sorted 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 listview control displaying a single column of values with an icon next to each item. It enables the user to select a value of a property from a pre-authored list of choices. This control supports single select listviews only. The possible values are read from the ListView Table.

Note The string displayed is not necessarily the same as the value that the user is choosing. If the control is created with the Sorted, the items are listed according to the Ordering column of the table. If the style bit is not set, the column is ignored.

Property

The property associated with this control can be string or integer valued.

Valid Style Bits

Enabled
FixedSize
IconSize
ImageHandle
Indirect
Integer
Sorted
Sunken
Visible

Valid Control Attributes

Enabled
Indirect
IndirectPropertyName
Position
PropertyName
PropertyValue
Text
Visible
WindowHandle

Control Events Published

None.

Can Take Focus

Windows: Yes.

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. 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.

< | 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.

Property

The property associated with this control must be a string.

Valid Style Bits

Enabled
Indirect
Sunken
Visible

Valid Control Attributes

Default
Enabled
Indirect
IndirectPropertyName
Position
PropertyName
PropertyValue
Text
Visible
WindowHandle

Control Events Published

None.

Can Take Focus

Yes.

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 upper-case.


PathEdit Control

This is a special control designed for use on a browse dialog. It is designed to be used with a DirectoryCombo and DirectoryList control on the same dialog. It displays the currently selected folder name or the entire path in an edit field. The property associated with this control has to have an initial value. This control also supports entering a full path in both modes. It first checks if the string enters is a valid path. If it is, it interprets the string as such. One can also enter a UNC path to a drive that has no drive letter associated with it.This control does not let the focus leave if the selection is not valid.

Property

The property associated with this control can be only string valued.

Valid Style Bits

Enabled
Indirect
Sunken
Visible

Valid Control Attributes

Default
Enabled
Indirect
IndirectPropertyName
Position
PropertyName
PropertyValue
Text
Visible
WindowHandle

Control Events Published

None.

Can Take Focus

Windows: Yes.

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.


RadioButtonGroup Control

This control is a group of radio buttons. It enables the user to select a value of a property from a pre-authored list of choices. The possible values are read from the RadioButton Table. Note that the string displayed is not necessarily the same as the value that the user is choosing. 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.

If the Bitmap or the Icon style bit is set, the corresponding text entry in the RadioButton Table is taken as a foreign key to the Binary table that specifies the binary data needed to create the picture on the individual buttons.

This means that the buttons cannot have both a picture and text.

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.

Property

The property associated with this control can be string or integer valued.

Valid Style Bits

Bitmap
Enabled
FixedSize
HasBorder
Icon
IconSize
ImageHandle
Indirect
Integer
PushLike
Sunken
Visible

Valid Control Attributes

Default
Enabled
Indirect
IndirectPropertyName
Position
PropertyName
PropertyValue
Text
Visible
WindowHandle

Control Events Published

None.

Can Take Focus

Yes.

Remarks

The group is created using the "BUTTON" class. If the HasBorder style is set, it has the BS_GROUPBOX style, otherwise it has the BS_OWNERDRAW style.

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.

If the PushLike style is set they have the BS_PUSHLIKE style.

If the Bitmap style is set they have the BS_BITMAP style.

If the Icon style is set they have the BS_ICON style.


SelectionTree Control

This special control is designed to present some of the information in the Feature Table to the user and allow the user to change the selection state of some items.

Property

String valued, the name of the directory property that will be set by the browse dialog.

Valid Style Bits

Enabled
Indirect
Sunken
Visible

Valid Control Attributes

Enabled
Indirect
IndirectPropertyName
Position
PropertyName
PropertyValue
Text
Visible
WindowHandle

Control Events Published

SelectionAction
SelectionBrowse
SelectionDescription
SelectionIcon
SelectionPath
SelectionPathOn
SelectionSize

Can Take Focus

Yes.

Related Strings in the UIText Table

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

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

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.

Note The selection tree gets populated only if the CostInitialize and CostFinalize actions were all previously called.


VolumeSelectCombo Control

This is a special control designed to a volume from a list of volumes. It lists the volumes in alphabetical order. The types of controls displayed is determined by the style bits of the control.

Property

The property associated with this control can be only string valued.

Valid Style Bits

CDROMVolume
Enabled
FixedVolume
FloppyVolume
Indirect
RAMDiskVolume
RemoteVolume
RemovableVolume
Sunken
Visible

Valid Control Attributes

Default
Enabled
Indirect
IndirectPropertyName
Position
PropertyName
PropertyValue
Text
Visible
WindowHandle

Control Events Published

None.

Can Take Focus

Windows: Yes.

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, but doing this ensures that screenreaders show the correct information.


Control Attributes

This section describes control attributes.


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.

Type

String.

Access

Read and Write.

Minimum Size of the Record

At least one field.

Control Types That Have This Attribute

Billboard

Associated Control Stylebit

None.


Default Control Attribute

This attribute describes if the given control is defined as the default control on the dialog. If it is the default, then pressing ENTER automatically activates this control.

Type

Boolean.

Access

Read and Write.

Minimum Size of the Record

At least one field.

Control Types That Have This Attribute

All controls.

Although this attribute is defined for every control, it is only practical for controls that have a button-like behavior.

Associated Control Stylebit

None.


Enabled Control Attribute

This attribute describes if the given control is enabled or disabled. Most controls have a gray disabled look. For some inert controls, changing this attribute results in no visible change.

Type

Boolean.

Access

Read and Write.

Minimum Size of the Record

At least one field.

Control Types That Have This Attribute

All controls.

Associated Control Stylebit

Enabled


Image Control Attribute

This attribute is the name of the image in the Binary Table. If the image is set by the ImageHandle attribute, this attribute does not reflect the correct name anymore.

Type

String.

Access

Read and Write.

Minimum Size of the Record

At least 1.

Control Types That Have This Attribute

Bitmap
Icon

Associated Control Stylebit

None.

Related Control Attribute

ImageHandle


ImageHandle Control Attribute

This attribute is the handle to the bitmap or icon displayed in the control. If the image is set by this attribute, the name of the image is not correct anymore and the Image attribute will return an incorrect value.

Type

String.

Access

Read and Write.

Minimum Size of the Record

At least 1.

Control Types That Have This Attribute

Bitmap
Icon

Associated Control Stylebit

None.

Related Control Attribute

Image


Indirect Control Attribute

This attribute determines for some active controls if the associated property is referenced indirectly.

Type

Boolean.

Access

Read only.

Minimum Size of the Record

At least 1 field.

Control Types That Have This Attribute

All active controls.

Associated Control Stylebit

Indirect


IndirectPropertyName Control Attribute

In case of an active control this attribute is the name of the associated indirect property. For inert controls this attribute returns Null.

An indirect property names an other property, and the control displays/changes the value of this second property.

Type

String.

Access

Read only.

Minimum Size of the Record

At least 1.

Control Types That Have This Attribute

Every control.

Associated Control Stylebit

None.

Related Control Attributes

PropertyName
PropertyValue


Position Control Attribute

This attribute determines the position of the control on the dialog. The four fields are: left, top, width, and height. The coordinates are in pixels and relative to the upper left corner of the dialog.

Type

Integer.

Access

Read and Write.

Minimum Size of the Record

At least 4.

Control Types That Have This Attribute

Every control.

Associated Control Stylebit

None.

Related Control Attributes

None.


Progress Control Attribute

This attribute measures how far the progress 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.

Type

Integer.

Access

Read and Write.

Minimum Size of the Record

At least 3.

Control Types That Have This Attribute

ProgressBar

Associated Control Stylebit

None.


PropertyName Control Attribute

In case of an active control this attribute is the name of the associated property. For inert controls this attribute returns Null.

Type

String.

Access

Read only.

Minimum Size of the Record

At least 1.

Control Types That Have This Attribute

Every control.

Associated Control Stylebit

None.

Related Control Attributes

IndirectPropertyName
PropertyValue


PropertyValue Control Attribute

This attribute is the present value of the associated property. If this attribute is changed, the control updates to show the new state.

Type

String or Integer depending on the Integer style of the control.

Access

Read and Write.

Minimum Size of the Record

At least 1.

Control Types That Have This Attribute

Every active control.

Associated Control Stylebit

None.

Related Control Attributes

IndirectPropertyName
PropertyName


Text Control Attribute

This attribute is the text string used 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.

Type

String.

Access

Read and Write.

Minimum Size of the Record

At least 1 field.

Control Types That Have This Attribute

Every control.

Associated Control Stylebit

None.


Transparent Control Attribute

If this attribute is set on a text control, it is displayed transparently, the background shows through the control where there are no characters. Otherwise the background is opaque.

Type

Boolean.

Access

Read only.

Minimum Size of the Record

At least 1.

Control Types That Have This Attribute

Text

Associated Control Stylebit

Transparent


Visible Control Attribute

If this attribute is set the control is visible, otherwise hidden.

Type

Boolean.

Access

Read and Write.

Minimum Size of the Record

At least 1.

Control Types That Have This Attribute

Every control.

Associated Control Stylebit

Visible


WindowHandle Control Attribute

This attribute returns the window handle to the control's window. Supported on Windows only.

Type

Integer.

Access

Read only.

Minimum Size of the Record

At least 1.

Control Types That Have This Attribute

Every control. Windows only!

Associated Control Stylebit

Visible


Control Stylebits

This section describes control stylebits.


Bitmap Control Stylebit

If this bit is set, the control's text is replaced by a bitmap. The text entry in the database that normally would specify the text of the control is used as a foreign key to the Binary table to point to the binary data needed for the picture. Such a control has no text associated with it. This style bit should not be set at the same time as the Icon stylebit.

Control Types that Can Have This Style

CheckBox

PushButton

RadioButtonGroup

Associated Control Attribute

Numeric Value

0x00040000 = 262144


CDROMVolume Control Stylebit

If this bit is set the control lists CDROM volumes in its list of volumes.

Control Types That Can Have This Style

DirectoryCombo
VolumeCostList
VolumeSelectCombo

Associated Control Attribute

None.

Related Control Stylebits

FixedVolume
FloppyVolume
RAMDiskVolume
RemoteVolume
RemovableVolume

Numeric Value

0x00080000 = 524288


ComboList Control Stylebit

If this bit is set on a combobox, the edit field is replaced by a static text field, therefore the user cannot enter a new value, can choose only one of the predefined values. Otherwise the combobox is drawn with an edit field.

Control Types That Can Have This Style

ComboBox

Associated Control Attribute

None.

Numeric Value

0x00020000 = 131072


Enabled Control Stylebit

If this bit is set the control control is created enabled, otherwise disabled. The enabled/disabled state of the control can be changed later through the associated attribute or by the publisher of some event that the given control subscribes to.

Control Types That Can Have This Style

All controls. On some controls (like Bitmaps and Icons) this bit makes no visible difference.

Associated Control Attribute

Enabled

Numeric Value

0x00000002 = 2


FixedSize Control Stylebit

If this bit is set the picture on the button or a bitmap or an icon control is displayed in its "natural size". If the picture is smaller than the control, it is centered, if the picture is larger, it is chopped in case of bitmaps but it is shrunk in case of icons. If the bit is not set, the picture is stretched to fit the button or control rectangle.

On CheckBoxes, PushButtons, and RadioButtonGroups this bit has any effect only if the Bitmap or the Icon is set.

On Icon controls and buttons associated with icons this bit is ignored if the IconSize bits are not set!

Control Types That Can Have This Style

Bitmap
CheckBox
Icon
PushButton
RadioButtonGroup

Associated Control Attribute

None.

Numeric Value

0x00100000 = 1048576


FixedVolume Control Stylebit

If this bit is set the control lists fixed internal hard drives in its list of volumes.

Control Types That Can Have This Style

DirectoryCombo
VolumeCostList
VolumeSelectCombo

Associated Control Attribute

None.

Related Control Stylebits

CDROMVolume
FloppyVolume
RAMDiskVolume
RemoteVolume
RemovableVolume

Numeric Value

0x00020000 = 131072


FloppyVolume Control Stylebit

If this bit is set the control lists floppy drives in its list of volumes.

Control Types That Can Have This Style

DirectoryCombo
VolumeCostList
VolumeSelectCombo

Associated Control Attribute

None.

Related Control Stylebits

CDROMVolume
FixedVolume
RAMDiskVolume
RemoteVolume
RemovableVolume

Numeric Value

0x00200000 = 2097152


HasBorder Control Stylebit

If this bit is set the RadioButtonGroup has 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 either!

Control Types That Can Have This Style

RadioButtonGroup

Associated Control Attribute

None.

Numeric Value

0x01000000 = 16777216


Icon Control Stylebit

If this bit is set, the control's text is replaced by an icon. The text entry in the database that normally would specify the text of the control is used as a foreign key to the Binary table to point to the binary data needed for the picture. Therefore, such a control has not text associated with it, only the picture. This stylebit should not be set at the same time as the Bitmap stylebit.

Control Types That Can Have This Style

CheckBox

PushButton

RadioButtonGroup

Associated Control Attribute

Numeric Value

0x00080000 = 5242288


IconSize Control Stylebits

An icon file can hold several different size images of the same icon. These two bits determine which size image of the icon is loaded. If neither bit is set, the first image is loaded. If only the lower bit is set, the first 16x16 image is loaded. If only the higher bit is set, the first 32x32 image is loaded. If both bits are set, the first 48x48 image is loaded.

If the FixedSize bit is set, these bits determine the size of the image displayed.

Control Types That Can Have This Style

CheckBox
Icon
PushButton
RadioButtonGroup

Associated Control Attribute

None.

Numeric Value

0x00200000 = 2097152
0x00400000 = 4194304


ImageHandle Control Stylebits

Controls that require an image normally specify the name of the binary information in the text field and the binary data is looked up from the Binary table using this key. If this style bit is set, it means that the binary information is NOT coming from the Binary table, but instead the text field represents the handle to a bitmap or icon (in a string format) and this already loaded icon or bitmap must be used by the control. Obviously these handles cannot be authored previously, the actual value of the handle in the table has to be set by some action that is performed prior to creating the control. A possible use is to have an action to find all the running applications and put their names and icons into the ListView Table, and the control can display these names and icons, Even if this bit is on, other stylebits governing the size and stretching of the image are still observed. As an example: if an action puts a handle of an image in the table, but other stylebits describe a different size, the image will be still stretched.

Control Types That Can Have This Style

Bitmap
CheckBox
Icon
ListView
PushButton
RadioButtonGroup

Associated Control Attribute

None.

Numeric Value

0x00010000 = 65536


Indirect Control Stylebit

If this bit is set on an active control, it means that the control changes the value of the property whose name is the value of the named property. Otherwise the named property is changed.

Control Types That Can Have This Style

All active controls.

Associated Control Attribute

Indirect.

Numeric Value

0x00000008 = 8


Integer Control Stylebit

If this bit is set on an active control, the associated property is integer valued. Otherwise the property is string valued.

Control Types That Can Have This Style

CheckBox
ComboBox
Edit
ListBox
RadioButtonGroup

Associated Control Attribute

None.

Numeric Value

0x00000010 = 16


Progress95 Control Stylebit

If this bit is set on a progress bar, it is drawn with small disjoint rectangles in Windows 95 style. Otherwise the bar is drawn continuously.

Control Types That Can Have This Style

ProgressBar

Associated Control Attribute

None.

Numeric Value

0x00010000 = 65536


PushLike Control Stylebit

If this bit is set on a checkbox or a radiobuttongroup the button is drawn with the visual appearance of a push button, but it's logic stays the same. If the bit is not set the controls are drawn in their usual visual style.

Control Types That Can Have This Style

CheckBox
RadioButtonGroup

Associated Control Attribute

None.

Numeric Value

0x00020000 = 131072


RAMDiskVolume Control Stylebit

If this bit is set the control lists RAM disks in its list of volumes.

Control Types That Can Have This Style

DirectoryCombo
VolumeCostList
VolumeSelectCombo

Associated Control Attribute

None.

Related Control Stylebits

CDROMVolume
FixedVolume
FloppyVolume
RemoteVolume
RemovableVolume

Numeric Value

0x00100000 = 1048567


RemoteVolume Control Stylebit

If this bit is set the control lists remote volumes in its list of volumes.

Control Types That Can Have This Style

DirectoryCombo
VolumeCostList
VolumeSelectCombo

Associated Control Attribute

None.

Related Control Stylebits

CDROMVolume
FixedVolume
FloppyVolume
RAMDiskVolume
RemovableVolume

Numeric Value

0x00040000 = 262144


RemovableVolume Control Stylebit

If this bit is set the control lists removable drives in its list of volumes.

Control Types That Can Have This Style

DirectoryCombo
VolumeCostList
VolumeSelectCombo

Associated Control Attribute

None.

Related Control Stylebits

CDROMVolume
FixedVolume
FloppyVolume
RAMDiskVolume
RemoteVolume

Numeric Value

0x00010000 = 65536


Sorted Control Stylebit

If this bit is set on a listbox or combobox, the items in the list are displayed in the order defined by the Ordering column of the corresponding table. If the bit is not set, the items are displayed in alphabetical order.

Control Types That Can Have This Style

ComboBox
ListBox
ListView

Associated Control Attribute

None.

Numeric Value

0x00010000 = 65536


Sunken Control Stylebit

If this bit is set on a control, it is displayed with a sunken, 3D look, if that is available on the system. Otherwise the control is displayed in its default visual style. The effect of this style bit is different on different versions of Windows. On most controls it has no visible effect.

Control Types That Can Have This Style

All controls.

Associated Control Attribute

None.

Numeric Value

0x00000004 = 4


Transparent Control Stylebit

If this bit is set on a text control, it is displayed transparently, the background shows through the control where there are no characters. Otherwise the background is opaque.

Control Types That Can Have This Style

Text

Associated Control Attribute

Transparent

Numeric Value

0x00010000 = 65536


Visible Control Stylebit

If this bit is set on a control, it is visible on the dialog. Otherwise it is hidden. The visible/hidden state of the control can be changed later through the associated attribute or by the publisher of some event that the given control subscribes to.

Control Types That Can Have This Style

All controls.

Associated Control Attribute

Visible

Numeric Value

0x00000001 = 1


Control Events

This section describes control events.


ActionData ControlEvent

The Handler uses this event to broadcast the latest action data.

Published By

Handler.

Argument

None.

Action on Subscribers

The subscribers are hidden when a new action starts and they are shown when a new action data arrives from the engine.

Action by Publisher When Subscriber Activated

None.

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. (For example the names of the files copied during file copy).


ActionText ControlEvent

The Handler uses this event to broadcast the name of the present action.

Published By

Handler.

Argument

None.

Action on Subscribers

The subscribers are shown when a new progress data arrives from the engine.

Action by Publisher When Subscriber Activated

None.

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 when a feature or all features have to be selected as local.

Published By

Handler.

Argument

A string, either the name of the feature or "ALL" (this second option is case insensitive).

Action on Subscribers

None.

Action by Publisher

When Subscriber Activated

The Handler keeps the present dialog running and notifies the installer.

Typical Use

A PushButton control on a modal dialog is tied to this event.


AddSource ControlEvent

The installer is notified through this event when a feature or all features have to be selected as source.

Published By

Handler.

Argument

A string, either the name of the feature or "ALL" (this second option is case insensitive).

Action on Subscribers

None.

Action by Publisher When Subscriber Activated

The Handler keeps the present dialog running and notifies the installer.

Typical Use

A PushButton control on a modal dialog is tied to this event.


CheckDiskSpace ControlEvent

To be written.


CheckExistingTargetPath ControlEvent

The Handler is notified through this event when it has to be verified that the selected path is writable. If the path is not writable, it blocks further control events associated with the same control.

Published By

Handler.

Argument

The name of the property containing the path. If the property is indirected, the property name is enclosed in square brackets.

Action on Subscribers

None.

Action by Publisher When Subscriber Activated

The path is checked.

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

The Handler is notified through this event when it has to be verified that the selected path is valid. If the path is not valid, it blocks further control events associated with the same control.

Published By

Handler.

Argument

The name of the property containing the path. If the property is indirected, the property name is enclosed in square brackets.

Action on Subscribers

None.

Action by Publisher When Subscriber Activated

The path is checked.

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.

Action by Publisher When Subscriber Activated

None.

Typical Use

Typically the DirectoryCombo control subscribes to the IgnoreChange control event.


DirectoryListNew ControlEvent

The DirectoryList control is notified through this event when a new folder must be created.

Published By

DirectoryList

Argument

None.

Action on Subscribers

None.

Action by Publisher When Subscriber Activated

Creates a new (ghost) folder and selects its name field for editing. If a ghost folder already exists in the current folder, that that folder is selected and its name is opened for editing.

Typical Use

A PushButton control on the same modal dialog as the DirectoryList subscribes to this event to trigger the creation of a new folder.


DirectoryListOpen ControlEvent

The DirectoryList control is notified through this event when the user wants to open the selected directory.

Published By

DirectoryList

Argument

None.

Action on Subscribers

The subscribers are disabled if there is no folder selected currently. Otherwise they are enabled.

Action by Publisher When Subscriber Activated

Changes the selection to the highlighted directory.

Typical Use

A PushButton control on the same modal dialog as the DirectoryList subscribes to this event to trigger stepping down in the path.


DirectoryListUp ControlEvent

The DirectoryList control is notified through this event when the user wants to select the parent of the present directory.

Published By

DirectoryList

Argument

None.

Action on Subscribers

The subscribers are disabled if the current directory has no parent (it is a volume), otherwise they are enabled.

Action by Publisher When Subscriber Activated

Changes the selection to the parent of the current directory.

Typical Use

A PushButton control on the same modal dialog as the DirectoryList subscribes to this event to trigger stepping up in the path.


DoAction ControlEvent

A dialog box notifies the user interface handler when a custom action should be executed.

Published By

User interface handler.

Argument

A string, the name of the custom action to be executed.

Action on Subscribers

None.

Action by Publisher When Subscriber Activated

The user interface handler runs the specified custom action.

Typical Use

A PushButton control on a dialog is tied to this event in the ControlEvent table to invoke a custom action.


EndDialog ControlEvent

The Handler is notified through this event when a modal dialog has to be removed.

Published By

Handler.

Argument

On regular dialogs: "Return", "Exit", "Retry", or "Ignore".

On error dialogs" "ErrorOk", "ErrorCancel", "ErrorAbort", "ErrorRetry", "ErrorIgnore", "ErrorYes", or "ErrorNo".

Action on Subscribers

None.

Action by Publisher When Subscriber Activated

In all cases the Handler removes the present dialog.

If the argument is "Exit", the wizard sequence is closed, the control returns to the Engine with the UserExit value.

If the argument is "Retry", the wizard sequence is closed, the control returns to the Engine with the Suspend value.

If the argument is "Ignore", the wizard sequence is closed, the control returns to the Engine with the Finished value.

The above three arguments can be used only on dialogs that are not children of some other dialog.

If the argument is "Return", the control returns to the parent of the present dialog, if there is a parent. If there is no parent, the control returns to the Engine with the Success value.

For buttons on an error dialog, the possible values correspond to the return codes to the Engine.

Typical Use

A PushButton control on a modal dialog is tied to this event in the ControlEvent table to dismiss a dialog.


NewDialog ControlEvent

The Handler is notified through this event when a modal dialog transitions to an other one.

Published By

Handler.

Argument

A string, the name of the new dialog.

Action on Subscribers

None.

Action by Publisher When Subscriber Activated

The Handler removes the present dialog and creates the new one with the name indicated in the argument.

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, typically with the push of a PushButton control.

Published By

Handler.

Argument

A string, either the name of the feature or "ALL" (this second option is case insensitive).

Action on Subscribers

None.

Action by Publisher When Subscriber Activated

The Handler keeps the present dialog running and notifies the installer.

Typical Use

A PushButton control on a modal dialog is tied to this event. Typically the same button is also tied to a ReinstallMode control event immediately preceeding this one.


ReinstallMode ControlEvent

This ControlEvent allows the author to specify the validation mode(s) to be used during a reinstall.

Published By

Handler.

Argument

A string. For the list of possible values, see the REINSTALLMODE Property.

Action on Subscribers

None.

Action by Publisher When Subscriber Activated

The Handler keeps the present dialog running and notifies the installer.

Typical Use

A PushButton control on a modal dialog is tied to this event. Typically the same button is also tied to a Reinstall control event immediately following this one.


Remove ControlEvent

The installer is notified through this event when a feature or all features have to be selected for removal.

Published By

Handler.

Argument

A string, either the name of the feature or "ALL" (this second option is case insensitive).

Action on Subscribers

None.

Action by Publisher When Subscriber Activated

The Handler keeps the present dialog running and notifies the installer.

Typical Use

A PushButton control on a modal dialog is 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. It should reset all the property values to what they were when the dialog was created.

There is one case that is not handled properly. If there are at least two controls on the same dialog linked indirectly to the same property and at least one of them started with some other property originally, this property value is sometimes reset to its second value. Since this case is very esoteric, it is not worth the special code to handle it.

Published By

Handler.

Argument

None.

Action on Subscribers

None.

Action by Publisher When Subscriber Activated

All the controls on the dialog are called to restore the original values of their properties.

Typical Use

A PushButton control on a modal dialog is tied to this event to allow resetting all the values on the dialog, canceling all the changes performed on the page.


SelectionAction ControlEvent

The SelectionTree control publishes this event that contains a string describing the action selected for the highlighted item. The string is one of the "Sel*" strings from the UIText Table.

Published By

SelectionTree

Argument

None.

Action on Subscribers

None.

Action by Publisher When Subscriber Activated

None.

Typical Use

A Text control on the same modal dialog as the SelectionTree subscribes to this event to display the explanation of the currently selected action.


SelectionBrowse ControlEvent

The SelectionTree control publishes this event that makes possible for another control (typically a button) to trigger the browse dialog for the currently highlighted item.

Published By

SelectionTree

Argument

The name of the dialog to be spawned.

Action on Subscribers

The subscribers are disabled or enabled depending on whether or not the path of the currently selected item can be modified by the user.

Action by Publisher When Subscriber Activated

Spawns a browse dialog to modify the path.

Typical Use

A PushButton control on the same modal dialog as the SelectionTree subscribes to this event to trigger the browse dialog.


SelectionDescription ControlEvent

The SelectionTree control publishes this event 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.

Action by Publisher When Subscriber Activated

None.

Typical Use

A Text control on the same modal dialog as the SelectionTree subscribes to this event to display the description of the highlighted item.


SelectionIcon ControlEvent

The SelectionTree control publishes this event that contains the handle to the icon indicating the selected action on the highlighted item.

Published By

SelectionTree

Argument

None.

Action on Subscribers

None.

Action by Publisher When Subscriber Activated

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.


SelectionPath ControlEvent

The SelectionTree control publishes this event that contains the path for the highlighted item. If the item is selected to run from source, this is the path of the source. If the item is selected to be absent, the string is the AbsentPath string from the UIText Table.

Published By

SelectionTree

Argument

None.

Action on Subscribers

None.

Action by Publisher When Subscriber Activated

None.

Typical Use

A Text control on the same modal dialog as the SelectionTree subscribes to this event to display the path of the highlighted item.


SelectionPathOn ControlEvent

The SelectionTree control publishes this event that is a Boolean value whether there is a selection path associated with the currently selected feature.

Published By

SelectionTree

Argument

None.

Action on Subscribers

None.

Action by Publisher When Subscriber Activated

None.

Typical Use

A Text control on the same modal dialog as the SelectionTree subscribes to this event as the caption of the selection path. This text control is turned visible or hidden depending on this event.


SelectionSize ControlEvent

The SelectionTree control publishes this event that contains the size for the highlighted item. If it is a parent item, it also contains the number of children selected. 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.

Action by Publisher When Subscriber Activated

None.

Typical Use

A Text control on the same modal dialog as the SelectionTree subscribes to this event to display the size of the highlighted item.


SetInstallLevel ControlEvent

The handler calls the engine to set the installation level to the value specified in the argument

Published By

Handler.

Argument

An integer. The new value of the installation level.

Action on Subscribers

None.

Action by Publisher When Subscriber Activated

The handler calls the engine to change the installation level.

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 Handler uses this event to broadcast install progress information to any subscribing controls. The name is the actual name of the action not SetProgress. In other words, the control has to subscribe to the event by naming the Action whose progress is being indicated.

Published By

Handler.

Argument

None.

Action on Subscribers

The subscribers are hidden when a new action starts or and they are shown when a new progress data arrives from the engine.

Action by Publisher When Subscriber Activated

None.

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 this 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, so it cannot be null. The argument will be formatted using the FormatText method, therefore it can contain any expression that the method can handle. The property values are evaluated at the moment of the control event.

Published By

Handler.

Argument

The new value of the property. {} for null.

Action on Subscribers

None.

Action by Publisher When Subscriber Activated

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 Handler is notified through this event when it has to be verified that the selected path is valid and writable. It also calls the DirectoryManager to set the target path. If the path is not valid, it blocks further control events associated with the same control.

Published By

Handler.

Argument

The name of the property containing the path. If the property is indirected, the property name is enclosed in square brackets.

Action on Subscribers

None.

Action by Publisher When Subscriber Activated

The path is checked and set.

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.


SpawnDialog ControlEvent

The Handler is notified through this event when a modal dialog wants to create a child.

Published By

Handler.

Argument

A string, the name of the new dialog.

Action on Subscribers

None.

Action by Publisher When Subscriber Activated

The Handler keeps the present dialog and creates the new one with the name indicated in the argument, placing it on top of the old one.

Typical Use

A PushButton control on a modal dialog is tied to this event in the ControlEvent table to create a child dialog, like a "Are you sure you want to cancel" dialog.


SpawnWaitDialog ControlEvent

This event pops up 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

Handler.

Argument

A dialog in the Dialog table.

Action on Subscribers

None.

Action by Publisher When Subscriber Activated

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 handler uses this event to broadcast the approximate time remaining, in seconds, for the current progress sequence.

Published By

Handler.

Argument

None.

Action on Subscribers

None.

Action by Publisher When Subscriber Activated

None.

Typical Use

A text control on a modeless dialog subscribes to this event (via the EventMapping table), using the TimeRemaining attribute to display the time remaining.


ValidateProductID ControlEvent

The ValidateProductID ControlEvent 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

Handler.

Argument

None.

Action on Subscribers

None.

Action by Publisher When Subscriber Activated

Validates the Product ID.

Typical Use

A PushButton control on a modal dialog is tied to this event. This 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

In the Microsoft® Windows® installer, actions serve the same purpose as functions in a programming language. An action encapsulates a typical function you can perform during installation or maintenance of your application. There is a very close relationship between actions and the installer database. In fact, many of the tables in the database can be viewed as serving the singular purpose of containing parameters used by a corresponding action. Almost all of the standard actions are linked to at least one of the tables.

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 that the application requires in the registry. This action uses the Registry table for its data.

    Note The need to write registry values into the HKCU and HKLM hives of the registry at installation will diminish in the future as part of the ZAW effort.


About Standard Actions

To increase the versatility of your setup program, use Microsoft® Windows® installer standard actions. The topics in this section cover the major areas of functionality that a standard action carries out, such as:

  • Ordering actions in a sequence table
  • Publishing standard actions
  • Searching standard actions
  • Costing standard actions


Ordering Actions in a Sequence Table

There are three top-level actions in the installer: INSTALL, ADVERTISE, and ADMIN. When one of these top-level actions is executed, the installer accesses the corresponding sequence tables. Sequence tables in the installer list actions in a logical order to perform an overall task. There are six sequence tables in the installer:

  • The InstallUISequence table
  • The InstallExecuteSequence table
  • The AdminUISequence table
  • The AdminExecuteSequence table
  • The AdvtUISequence table
  • The AdvtExecuteSequence table

All three 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.
Sequence | A relative sequence number used to determine the order in which to execute actions.

When a top-level action is invoked actions in the sequence table are done in the sequence order. If the condition evaluates to True, the action is executed. Sequence tables are the only place in a package where flow is specified, and the flow is always linear. No branching or looping is allowed. Conditions can be thought of as jumps so the linear flow may not execute every action. This simplicity makes following the sequence of events during an installation trivial.


Publishing Standard Actions

To publish a product, component, or feature, you use one of the publishing actions. The PublishProduct action registers the product information with the system. After executing the PublishProduct action, you publish components with the PublishComponents action, which uses the PublishComponent table to determine the components that are set to be advertised. To publish on a per-feature basis, the PublishFeatures action is invoked. This action uses the FeatureComponents table as data to resolve which features must be advertised.

There are also two corresponding actions that unpublish a feature or a component: the UnpublishComponents action and the UnpublishFeatures action.


Searching Standard Actions

During installation, you often need to search for a file. The installer has four standard search actions that serve this purpose. The AppSearch action uses the AppSearch table to determine if a file exists on a user's computer. The CCPSearch action and the RMCCPSearch action use corresponding tables to check for a previous version of a product for an upgrade installation.


Costing Standard Actions

Costing is the process of determining the total disk space requirements for the current installation, including costs for files to be installed and/or removed, registry entries, shortcuts, and so forth. Costing takes into account the size of existing files to be overwritten (which reduces the overall costs).

Total costs are accumulated on a per-component basis and consist of three separate parts: local costs, source costs, and removal cost—corresponding 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 in part on the 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 change in directory 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. This action initializes all internal routines that dynamically calculate the disk costs involved with all standard installation actions. No other dynamic cost calculations are done at this point.

Next, the CostFinalize action must be called. This action finalizes all the cost calculations and makes them available through the Component table.

After the CostFinalize action finishes, the Component table is fully initialized, and a user interface dialog box sequence containing a SelectionTree control (if needed) can be initiated. The user interface dialog boxes typically give the user the option to change the selection state and/or destination directory of any feature in the Feature table (which in turn is linked to one or more components). The process is similar when the selection state of a component changes, but, in this case, the dynamic cost of only the changed component is recalculated.

After the Selection user interface wizard sequence, the InstallValidate action should be called before any other installation action. This action verifies that all volumes to which cost has been attributed have sufficient space for the installation.


Using Standard Actions

You execute an action in the Microsoft® Windows® installer by calling the MsiDoAction function or by including the action in a sequence table. Since 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 actions, called top-level actions, that call sequence tables. The three associated sequence tables can contain standard actions, custom actions, and user-interface elements. Each action in a sequence table has a condition and a sequence number. All actions in a sequence table are visited in order and are executed if the condition evaluates to True.

Many of the installer standard actions have sequence restrictions. For example, before calling the FileCost action, you must first call the CostInitialize action. Actions can be ordered in any manner in a sequence table as long as they follow all the sequencing restrictions. For more information on restrictions, see the individual action topic in Standard Actions Reference.

The INSTALL action is a top-level action that uses the sequence tables.

Example

When the INSTALL action is executed, a typical installation sequence would have the following execution flow:

  1. LaunchConditions action is executed. All of the launch conditions must be satisfied for the installation to proceed.
  2. AppSearch action is executed. This action determines if an application specified in the AppSearch table is installed on the computer. This action can be used to determine the presence of a previous version of the application to be installed.
  3. CostInitialize action is executed. This action loads the Component table and the Feature table into memory to determine disk space requirements.
  4. FileCost action is executed. This action uses the loaded Feature table and Component table to determine the size of all files to be installed.
  5. CostFinalize action is executed. This action finalizes the costing information, taking into account the installation levels and conditions for selected features.
  6. First installation dialog box displays.

    If the entry in the sequence is not a standard action, the installer queries the CustomAction table to check whether the action is a registered custom action. If it is not a standard action or a custom action, the installer queries the user interface handler to check whether the action is a user interface element to be displayed.

  7. Progress dialog box displays.
  8. RegisterProduct action is executed. The product information is registered with the configuration manager.
  9. InstallValidate action is executed. This action verifies that all volumes for which the cost has been determined have sufficient space for installation.
  10. RegisterUser action is executed. This action registers user information in the configuration manager.
  11. CreateFolders action is executed. This action creates empty folders for components set to be installed.
  12. RemoveFiles action is executed. If there are files from a previous version, they are removed.
  13. InstallFiles action is executed. All files from components set to be installed are copied to the appropriate directory.
  14. MoveFiles action is executed. This action locates files that already exist on the user's computer and moves or copies those files to a new location.
  15. WriteRegistryValues action is executed. This action writes application registry information into the registry.
  16. CreateShortcuts action is executed. This action uses the Shortcut table to determine the shortcuts that must be copied to the computer.
  17. ProcessComponents action is executed. This action registers the component information for the components set to be installed.
  18. InstallFinalize action is executed. This action runs a script containing all operations spooled since the start for the installation.


Standard Actions Reference

The Microsoft® Windows® installer contains the following standard actions.

  • ADMIN
  • ADVERTISE
  • AppSearch
  • BindImage
  • BlockInstall
  • CCPSearch
  • CostInitialize
  • CostFinalize
  • CreateFolders
  • CreateShortcuts
  • ExecuteAction
  • FindRelatedProducts
  • ForceReboot
  • INSTALL
  • InstallAdminPackage
  • InstallFiles
  • InstallExecute
  • InstallFinalize
  • InstallInitialize
  • InstallValidate
  • LaunchConditions
  • MigrateFeatureSettings
  • MoveFiles
  • ODBCInstall Action
  • ODBCRemove Action
  • PatchFiles
  • ProcessComponents
  • PublishComponents
  • PublishFeatures
  • PublishProduct
  • RegisterFonts
  • RegisterProduct
  • RegisterProgIdInfo
  • RegisterTypeLibraries
  • RegisterUser
  • RemoveFiles
  • RemoveFolders
  • RemoveIniValues
  • RemoveOldProducts
  • RemoveRegistryValues
  • RemoveShortcuts
  • ResolveSource
  • RMCCPSearch
  • ScheduleReboot
  • SelfRegModules
  • SelfUnregModules
  • SetODBCFolders Action
  • RegisterClassInfo
  • RegisterExtensionInfo
  • RegisterMIMEInfo
  • UnpublishFeatures
  • UnpublishComponents
  • UnregisterClassInfo
  • UnregisterExtensionInfo
  • UnregisterFonts
  • UnregisterMIMEInfo
  • UnregisterProgIdInfo
  • UnregisterTypeLibraries
  • UpdateResources
  • ValidateProductID
  • WriteIniValues
  • WriteRegistryValues


ADMIN Action

The Admin action is a top-level action that is used to install an Admin image for workgroup use.

Database Tables Queried

The Admin action queries the following sequence tables for the action to execute, the condition for action execution, and the place of the action in the sequence.

InstallUISequence Table

InstallExecuteSequence Table

AdminUISequence Table

AdminExecuteSequence Table

AdvtUISequence Table

AdvtExecuteSequence Table

Properties Used

None

Sequencing Restrictions

The Admin action is not called from within the action table sequence.

Remarks

The application of transforms during the creation of an Admin image has no valid effect. Therefore to make a customized version of a product available to a workgroup, the transform should be applied during the installation of the product from the Admin image.


ADVERTISE Action

The ADVERTISE action is a top-level action that is called to install or remove advertised components.

Database Tables Queried

The ADVERTISE action queries the following sequence tables for the action to execute, the condition for action execution, and the place of the action in the sequence.

AdvtUISequence Table

AdvtExecuteSequence Table

Properties Used

None

Remarks

Advertisement involves placing information with the system to allow either explicit or implicit Just-in-Time installation of features of a product when needed.

When the installer is in install mode, advertise information for all enabled features.


AppSearch Action

The AppSearch action uses file signatures to determine whether an application exists on a user's computer. The action works on the AppSearch table. The AppSearch action is used to search for previous versions of products to determine where to install an upgrade.

Database Tables Queried

AppSearch

AppSearch.Property | Property to be set on existence of a file signature.
AppSearch.Signature_ | File signature.

Properties Used

None

Sequencing Restrictions

None

Remarks

For each Property/Signature_ pair in the table, the file signature, as specified in the Signature table, is searched for on the user's computer using the CompLocator, RegLocator, IniLocator, and DrLocator tables (in that order). The absence of the signature from the Signature table denotes a directory. If the signature is determined to exist, the corresponding Property is set to the directory path for that signature.


BindImage Action

The BindImage action binds each executable that must be bound to the DLLs imported by it. This action does this by computing the virtual address of each function that is imported from all DLLs. The computed virtual address is then saved in the importing image Import Address Table (IAT). The action works on each file referred to in the BindImage table installed locally.

Database Tables Queried

This action queries the BindImage table and the Component table.

Properties Used

None

Sequencing Restrictions

The BindImage action must be sequenced after the InstallFiles action.


BlockInstall Action

The BlockInstall action displays an error dialog and then blocks the current installation if the FindRelatedProducts action finds a newer version of the product on the system.

Database Tables Queried

This action queries the Operator and Property columns of the Upgrade table. The value of the operator specifies whether to block the installation of the pending upgrade of the product.

Properties Used

The BlockInstall action terminates the installation if the properties set by the FindRelatedProducts action are set when the action executes.

Remarks

The BlockInstall action only stops the installation if the properties are still set when the action is executed. For example, a dialog may be authored that warns the user that a newer version of the application has been found. If the user chooses to perform the current install anyway, the dialog may unset the appropriate property to allow the installation to proceed.


CCPSearch Action

The CCPSearch action uses file signatures to ensure that a user who acquires an upgrade version of a product actually has installed one of the qualifying upgrade products. The action works on the CCPSearch table.

Database Tables Queried

CCPSearch

CCPSearch.Signature_ File signature

Properties Used

None

Sequencing Restrictions

The CCPSearch action must be sequenced before the RMCCPSearch action.

Remarks

Each file signature, Signature_, in the table is searched for on the user's computer as specified in the Signature table using the CompLocator, RegLocator, IniLocator, and DrLocator tables (in that order). The absence of the signature from the Signature table denotes a directory. If any signature is determined to exist, the property CCP_Success is set to 1, and the CCPSearch action terminates.


CostFinalize Action

The CostFinalize action is used to finalize the costing information for each component in the Component table, making use of the authored InstallLevel for each Feature item in conjunction with the conditions specified in the Condition table.

CostFinalize also validates that all configurable target directories are writable before allowing the install to continue.

Database Tables Queried

Component Table

Condition Table

Properties Used

None

Sequencing Restrictions

The CostInitialize action, and any specific cost-calculation actions (such as FileCost), must be executed prior to executing CostFinalize. In turn, CostFinalize must be executed before starting any user interface dialog sequence that allows the user to view or modify Feature table selections or directories.


CostInitialize Action

The CostInitialize action starts the internal installation costing process. The CostInitialize action is also responsible for loading the Component and Feature tables into memory.

Database Tables Queried

Component Table

Feature Table

Properties Used

None

Sequencing Restrictions

Typically, after the CostInitialize action is called, the FileCost action is called. Next, the CostFinalize action is called, which finalizes all the cost calculations and makes them available via the Component table.

Remarks

Costing is the process in which the installer determines the disk space requirements for all the components comprising an installation, taking into account factors such as whether or not existing files need to be overwritten. For more information on the costing process in the installer, see Costing Standard Actions.


CreateFolders Action

The CreateFolders action creates empty folders for components set to be installed locally. When a folder is created (and didn't already exist), it is registered with the appropriate component identifier.

Database Tables Queried

CreateFolder

Component

CreateFolder.Directory_ | Folder name. For each folder, a property is assumed to exist with this name that defines the folder location.
Component.ComponentId | Component ID for the component owning this folder.

Properties Used

Each folder name in the CreateFolder table also is assumed to be a property defining the folder location.

Sequencing Restrictions

The CreateFolders action must be executed before the InstallFiles action or any action that may add files to folders.

Remarks

The removal of these folders is handled by the RemoveFolders action.


CreateShortcuts Action

The CreateShortcuts action manages the creation of shortcuts.

Database Tables Queried

Shortcut Table

Properties Used

None

Sequencing Restrictions

The CreateShortcuts action must be sequenced after the InstallFiles action and the RemoveShortcuts action.

Remarks

In advertise mode, the action creates shortcuts to the key files of components of features that are enabled. Advertised shortcuts are those for which the Target column in the Shortcut table is the feature of the component and the directory of the shortcut is one of the Shell folders or is below one. Advertised shortcuts are created with an installer descriptor as the target. Non-advertised shortcuts are those for which the Target column in the Shortcut table is a property or the directory of the shortcut is not one of the Shell folders or is below one. Advertised shortcuts are created with an installer descriptor as the target.

In non-advertise mode (normal install), the action creates shortcuts to the key files of components of features that are selected for install as well as non-advertised shortcuts whose components are selected for install.


DuplicateFiles Action

The DuplicateFiles action allows the author to make one or more duplicate copies of 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.

Database Tables Queried

DuplicateFile Table

Component Table

DuplicateFile.FileKey | Primary key, uniquely identifying an entry in the MoveFile table.
DuplicateFile.Component_ | Foreign key into the Component table.
DuplicateFile.File_ | Foreign key into the File table, representing the original file to be duplicated.
DuplicateFile.DestName | Name to be given to the destination file.
DuplicateFile.DestFolder | Property name whose value identifies the destination folder.

Properties Used

None

Sequencing Restrictions

The DuplicateFiles action must occur after the InstallFiles action.

Remarks

The DuplicateFiles action processes a DuplicateFile table entry only if the component linked to that entry is being installed locally.

The string in the DestFolder field is a property name whose value is expected to resolve to a fully qualified path. This property could 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.

For a particular entry in the DuplicateFile table, if the DestFolder property does not evaluate to a valid path, DuplicateFiles does nothing for that entry.

The name to be given to the destination file can be specified in the DestName field. If this field is left blank, the destination file name is the same as the original file name.

Files installed by the DuplicateFiles action are uninstalled when appropriate by the RemoveDuplicateFiles action.


ExecuteAction Action

The ExecuteAction action runs the top-level action defined by the EXECUTEACTION property.

Database Tables Queried

None

Properties Used

The ExecuteAction action checks the EXECUTEACTION property to determine with which top-level action to begin the execution sequence.

Sequencing Restrictions

This action should be placed in the sequence after the collection all of the information necessary to begin the installation. Additional actions can be placed after ExecuteAction action in the InstallUISequence table, AdminUISequence table, and the AdvtUISequence table. A typical sequence will begin with costing actions, such as the CostInitialize action, followed by the user interface actions, and then the ExecuteAction action.

Remarks

This 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 to the ExecuteAction action means to run the execution or the user interface sequence.


InstallExecute Action

The InstallExecute action runs a script containing all operations spooled since the start of the install or the last InstallFinalize action. It updates the system without ending the transaction.

Database Tables Queried

None

Properties Used

None

Sequencing Restrictions

This action occurs in the sequence between the InstallInitialize action the InstallFinalize action.

Remarks

The InstallExecute action is similar to the InstallFinalize action but InstallExecute does not end the transaction. This action will update the system with whatever operations have been determined to that point.


InstallFinalize Action

The InstallFinalize action runs a script containing all operations spooled since the start of the install or the last InstallFinalize action. It marks the end of a transaction that begins with the InstallInitialize action. If it is detected that the product is marked for complete removal, operations are added to the script to remove 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.

Database Tables Queried

None

Properties Used

None

Sequencing Restrictions

The InstallInitialize action must be called before the InstallFinalize action.

Remarks

When this action is executed, system changes made before it may not be restored. This action updates the system with whatever operations have been determined to that point, 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.

Database Tables Queried

None

Properties Used

None

Sequencing Restrictions

The InstallInitialize action must be called before any actions that change the system, such as the InstallFiles action, WriteRegistryValues action, and ProcessComponents action. It must, therefore, be called before the InstallFinalize action and the InstallExecute action.


FileCost Action

The FileCost action enables dynamic costing of standard installation actions.

Database Tables Queried

File Table

Component Table

Properties Used

None

Sequencing Restrictions

The CostInitialize action must be executed before executing the FileCost action. The installer is then responsible for determining the actual disk space cost of every file in the File table, on a per-component basis, taking into account volume clustering and the presence of existing files that may need to be overwritten. All actions that consume or release disk space are considered. In case an existing file is found, a file version check is performed to determine whether the new file actually needs to be installed. If the existing file is an equal or greater version, the existing file is not overwritten and no disk space cost is incurred. In any case, the installer uses the results of version checking to set the install state of each file.

The FileCost action itself simply initializes cost calculation with the installer. Actual dynamic costing does not occur until the CostFinalize action is executed.


FindRelatedProducts Action

The FindRelatedProducts action uses the Upgrade table to search for related products on the system. If a related product is found to be installed, then the action sets the property in the Property column of the Upgrade table.


ForceReboot Action

The ForceReboot action is authored in the sequence if there is a need to reboot during the installation before it can continue. The action writes a registry key that causes the installer to start after reboot. It also runs all spooled operations before reboot.

Database Tables Queried

None

Properties Used

None

Sequencing Restrictions

The ForceReboot action must be preceeded by the InstallValidate action and placed at the point in the installation sequence where the reboot is required.


INSTALL Action

The INSTALL action is a top-level action called to install or remove components.

Database Tables Queried

The INSTALL action queries the following sequence tables for the action to execute, the condition for action execution, and the place of the action in the sequence.

InstallUISequence Table

InstallExecuteSequence Table

AdminUISequence Table

AdminExecuteSequence Table

AdvtUISequence Table

AdvtExecuteSequence Table

Properties Used

None


InstallAdminPackage Action

The InstallAdminPackage action copies the product database to the admin install point, which is defined by the TARGETDIR property. This action also updates the summary information of the database and removes any cabinets located in streams once the database is copied.

Database Tables Queried

None

Properties Used

TARGETDIR

Sequencing Restrictions

None


InstallFiles Action

The InstallFiles action copies selected files from the source directory to the destination directory.

The InstallFiles action operates on files specified in the File table. Each of these files is installed based on what is going to happen to its associated component in the Component table. Only those files whose components are resolved to the iisLocal Action state are eligible to be copied.

Database Tables Queried

Media Table

File Table

Component Table

Media.LastSequence | Last sequence number on this media record.
Media.DiskPrompt | Text identifier on media, for user prompting (localized text).
Media.VolumeLabel | Volume label, used for disk validation.
Media.Cabinet | For cabinet installs, the name of the cabinet file.
File.FileName | Target file name (localized text).
File.Version | File version (non-localized text).
File.State | Installation status for the file (integer).
File.Attributes | File and installation attribute flag bits (integer).
File.File | Unique file token (non-localized text, primary key).
File.FileSize | Uncompressed file size in bytes (long integer).
File.Language | File language identifier (integer).
File.Sequence | Sequence number on media (integer, unique).
Component.Directory_ | Reference to Directory table item (non-localized text).
Component.Component | Unique name for the component item (text, primary key)
Component.Action | Enum indicating the action to be taken.

Properties Used

None

Sequencing Restrictions

The InstallFiles action must occur after the InstallValidate action and before any file-dependent actions.

Remarks

Action states determine what is going to happen to a file during the running of the installation script. However, even if the component is in the iisLocal state, the file is only copied if one of the following is true:

  • The file is currently not on the local computer.
  • The file is on the local computer but it 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 value in the Action state is calculated during the file costing process. For more information, see the Feature table and the FeatureRequestState property.

Source Directory Determination

The determination of the source directory for each file to be copied depends on the SourceMode, which is dependent on the value in the Media.Cabinet column. For a full discussion of the SourceMode determination, see the Media table.

Prompting for Disks

If the source directory for a file to be copied resides on a removable disk (a floppy or CD-ROM), the InstallFiles action validates that the proper source disk is inserted before attempting to copy the file. To do this, InstallFiles searches for a disk of the same removable type that has a volume label that matches the value given in the Media.VolumeLabel field. If a matching mounted volume is found, the file copying process proceeds. However, if no match is found, a dialog appears requesting that the proper disk be inserted. In this case, the dialog uses the disk name found in the Media.DiskPrompt field as part of the prompt.

Possible Problems

If a file is replacing an older file, an error occurs, and that error is ignored, it is possible that the original file is deleted and not replaced. This is because the installer deletes the old file before making sure the new file is copied correctly.


InstallValidate Action

The InstallValidate action verifies that all volumes to which cost has been attributed have sufficient space for the installation. If any volume is short of disk space, the InstallValidate action ends the installation with a fatal error.

This action is also responsible for notifying the user if one or more files to be overwritten or removed are currently in use by an active process.

Database Tables Queried

None

Properties Used

None

Sequencing Restrictions

The CostFinalize action and any user-interface dialog sequences that allow the user to modify selection states and/or directories should be executed prior to executing InstallValidate.

Remarks

This is a fail-safe verification. Typically, an earlier user-interface dialog sequence should perform this same verification whenever the user attempts to initiate the actual installation of files and should present an Out-Of-Disk-Space dialog when required. Thus, the user-interface dialogs should be authored in such a way as to prevent the user from proceeding with the install if a disk-space problem exists. Of course, in the case of a quiet install, there is no user interface, so the fact that InstallValidate action simply terminates the install if a disk-space problem exists is the proper response. (If logging is enabled, the reason for the premature termination appears in the log.)

Handling Files in Use

During the file costing process, for any file to be overwritten or removed that is also found to be in use (that is, opened for execution or modification by any process), an entry is added to an internal FilesInUse table. (This entry contains columns for the name and full path of the file.) When InstallValidate is executed, if there are any entries in the FilesInUse table, The installer determines the name of the process that is using the file. For each unique process identified in this manner, InstallValidate adds one record to the ListBox user-interface table, with the following values in each column:

Property: FileInUseProcess
Value: <Name of process>
Text: <Text contained in the caption of main window of process>

Next, InstallValidate displays the FilesInUse dialog. This gives the user interface a chance to display a dialog informing the user of the processes that should be shut down to avoid the requirement of rebooting the system to replace files in use. To display an appropriate dialog, a dialog must be authored with the name FilesInUse. This dialog must contain a ListBox control that is tied to a property named FileInUseProcess. By convention, this dialog would have three pushbuttons (for example, Exit, Retry, Ignore), but this is up to the user-interface author. In any case, each pushbutton should be tied to an EndDialog controlevent via the ControlEvent table, each with a different argument. InstallValidate responds as follows to the value returned by DoAction, 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 iesSuccess.

Exit: InstallValidate immediately returns control to the installer with a status of iesUserExit. This terminates the installation.

Any other return value: InstallValidate immediately returns control to the installer with a status of iesSuccess. 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 at reboot time.

Notes If no dialog named FilesInUse is found, or if the database has no ListBox table, InstallValidate silently exits without an error.

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

Files marked read-only in a read-only location are never considered in use by the installer.

If the UI level is basic, an "out of disk space" dialog is always presented to the user, when selecting the "Abort" and "Retry" buttons. To determine if sufficient disk space is available, see CheckDiskSpace ControlEvent.


LaunchConditions Action

The LaunchConditions action evaluates the set of conditions that must be satisfied for the installation to proceed. If any of these conditions fail, then an error message is displayed to the user and the installation is terminated.

Database Tables Queried

LaunchCondition Table

LaunchCondition.Condition | Expression, containing properties, to evaluate.
LaunchCondition.Description | Text to display if condition fails.

Properties Used

Only properties contained within the condition expressions.

Sequencing Restrictions

The LaunchConditions action is optional but, if present, should be the first action. If some of the conditions do not apply to all modes, the appropriate property should be included in the expression.


MigrateFeatureSettings Action

The MigrateFeatureSettings action sets the feature settings of the current installation equal to the feature settings of a product that is already installed.

Database Tables Queried

The MigrateFeatureSettings action queries the Operator column of the Upgrade table. This action migrates the feature settings from a product found by the FindRelatedProducts action if the Operator column in the Upgrade table contains the bit: 16.

Properties Used

None

Sequencing Restrictions

The MigrateFeatureSettings action should come after the CostInitialize action but before the UI wizard begins.


MoveFiles Action

The MoveFiles action allows the author to locate files that already exist on the user's computer and move or copy those files to a new location. The MoveFiles action moves an entry in the MoveFile table only if the component linked to that entry is being installed locally or is being run from source.

Database Tables Queried

MoveFile Table

Component Table

MoveFile.FileKey | Primary key, uniquely identifying an entry in the MoveFile table.
MoveFile.Component_ | Foreign key into the Component table.
MoveFile.SourceName | Name of the source file to be moved or copied.
MoveFile.DestName | Name to be given to the destination file.
MoveFile.SourceFolder | Property name whose value identifies the source folder.
MoveFile.DestFolder | Property name whose value identifies the destination folder.
MoveFile.Options | Option flags used to define the behavior of the move/copy operation.

Properties Used

None

Sequencing Restrictions

The LaunchConditions action must occur after the InstallValidate action and before the InstallFiles action.

Remarks

The Options field allows you to specify whether the source file(s) should be moved or copied (that is, whether the source file is to be deleted after it has been copied to a new location). For the exact syntax, see the MoveFile table.

The strings in the SourceFolder and DestFolder fields are property names whose values are expected to resolve to fully qualified paths. These properties could 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.

Some properties can contain a full path to a specific file (that is, a full path with the file name appended). For example, AppSearch can be authored to search for a particular file and to set a property to the full path to that file. In a case such as this, the SourceName field in the MoveFile table can be left blank indicating that the value in the SourceFolder property contains a full file path. Since the list delimiter for transforms, sources and patches is a semicolon, this character should not be used in these filenames or paths.

For a particular entry in the MoveFile table, if either the SourceFolder or DestFolder property does not evaluate to a valid path, MoveFiles does nothing for that entry.

The MoveFiles action attempts to move or copy all files in the source directory that match the name given in the SourceName column. This name can include wildcards (* and ?), which allow a group of files to be moved or copied. For example, you could specify *.xls for the SourceName, and MoveFiles moves or copies every Microsoft® Excel workbook from the source directory to the destination.

When copying or moving files, the name to be given to the destination file can be specified in the DestName field. If this field is left blank, the destination file name is the same as the source file name.

The DestName field should normally be left blank if a wildcard is specified in the SourceName field. If you do specify a DestName when using wildcards, the first source file that matches the wildcard criteria is given the specified destination name. (All other moved/copied files have the same name as the source file.)

Files that are moved or copied by MoveFiles are not deleted when the product is uninstalled.


ODBCInstall Action

The ODBCInstall 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 action will make SQL calls necessary to carry out their installation.

Database Tables Queried

The ODBCInstall action queries the ODBCDataSource table and the ODBCSourceAttribute table for each data source to be installed and the attributes of the data source. The action queries the ODBCDriver table and the ODBCTranslator table for each driver and translator selected for installation. It queries the ODBCAttribute table for the attributes of the drivers and translators.

Sequencing Restrictions

This action does not copy or remove files and therefore must come after actions that copy or remove files.

Remarks

The ODBC Driver Manager must be authored in the installer package and a component included named ODBCDriverManager. The manager will be installed if necessary. If this component must have another name, a property with the name ODBCDriverManager must contain the name of the component.


ODBCRemove Action

The ODBCRemove action removes the data sources, translators, and drivers that are listed for removal during the installation.

Database Tables Queried

This action queries the ODBCDataSource table, the ODBCTranslator table, or the ODBCDriver table for each data source, translator, or driver to be removed.

Properties Used

None

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 based on SharedDLLs key ref counts.


ProcessComponents Action

The ProcessComponents action manages information regarding the product components. The action is responsible for the registration and unregistration of components and component clients.

Database Tables Queried

Component Table

File Table

Properties Used

None

Sequencing Restrictions

The ProcessComponents action must be called after the InstallFiles action.


PatchFiles Action

The PatchFiles action queries the Patch table to determine what patches are applied to which files and then performs the necessary byte-wise patching of the files receiving a patch.

Database Tables Queried

The PatchFiles action queries the Patch table and File table and Component table.

Sequencing Restrictions

A file must be installed to be patched. Therefore the PatchFiles action must come after the InstallFiles action that installs the file or the file must have been already installed.


PublishComponents Action

The PublishComponents action manages the advertisement of the components from the PublishComponent.

Database Tables Queried

This action queries the PublishComponent Table, the Feature Table, and the Component Table.

Properties Used

None

Sequencing Restrictions

None

Remarks

This 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 manages the advertisement of the feature composition (feature-component mapping) within the system.

Database Tables Queried

The PublishFeatures action queries the FeatureComponents table, the Feature table, and the Component table.

Properties Used

None

Sequencing Restrictions

None

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 it is in advertise mode or if MsiGetProductInfo returns ERROR_INSTALL_PRODUCT for the product.

Database Tables Queried

Icon Table

Properties Used

None

Sequencing Restrictions

The PublishProduct action is must come before the PublishFeatures action.


RegisterClassInfo Action

The RegisterClassInfo action manages the registration of COM class information with the system. In advertise mode, the action registers all COM classes from the Class table for which the corresponding feature is enabled. Else the action registers COM classes from the Class table for which the corresponding feature is currently selected to be installed.

Database Tables Queried

Class Table

Properties Used

None

Sequencing Restrictions

The RegisterClassInfo action must be sequenced after the InstallFiles and the UnregisterClassInfo actions.

Remarks

In advertise mode, the action registers all COM classes from the Class table for which the corresponding feature is enabled. Else the action registers COM classes from the Class table for which the corresponding feature is currently selected to be installed.


RegisterExtensionInfo Action

The RegisterExtensionInfo action manages the registration of extension related information with the system.

Database Tables Queried

Extension Table

Verb Table

Properties Used

None

Sequencing Restrictions

The RegisterExtensionInfo action must be sequenced after the InstallFiles and the UnregisterExtensionInfo actions.

Remarks

In advertise mode, the action registers all extension servers from the Extension table for which the corresponding feature is enabled. Else the action registers extension servers from the Extension table for which the corresponding feature is currently selected to be installed.


RegisterFonts Action

The RegisterFonts action registers installed fonts with the system. This action maps the Font.FontTitle to the path of the font file installed.

Database Tables Queried

Font Table

File Table

Component Table

Properties Used

None

Sequencing Restrictions

The InstallFiles action must be called before calling RegisterFonts.

Remarks

The RegisterFonts action is triggered when the component to which the Font.File_ belongs is selected for install. This implies that fonts can be made private, shared, or system by specifying the components to which they belong.


RegisterMIMEInfo Action

The RegisterMIMEInfo action registers the MIME-related registry information with the system.

Database Tables Queried

MIME Table

Properties Used

None

Sequencing Restrictions

The RegisterMIMEInfo action must be sequenced after the InstallFiles and the UnregisterMIMEInfo actions.

Remarks

In advertise mode, the action registers all MIME info for servers from the MIME table for which the corresponding feature is enabled. Else the action registers MIME info for servers from the MIME table for which the corresponding feature is currently selected to be installed.


RegisterProduct Action

The RegisterProduct action registers the product information with the installer. Additionally, it stores the installer database on the local computer.

Database Tables Queried

None

Properties Used

The RegisterProduct action uses the ARPNOMODIFY property and the ARPNOREMOVE property. If these properties are set, then the RegisterProduct action will disable Add/Remove Control Panel and Programs Wizard functionality that would modify or remove products.

Sequencing Restrictions

None

Remarks

The RegisterProduct action is not performed during the AdminInstall.


RegisterProgIdInfo Action

The RegisterProgIdInfo action manages the registration of OLE ProgId information with the system. This action registers all ProgId information from the ProgId table for features that are connected to the extension information (in the Extension table) or the Class information (in the Class table) that are enabled to be advertised or selected to be installed.

Database Tables Queried

ProgId Table

Class Table

Extension Table

Properties Used

None

Sequencing Restrictions

The RegisterProgIdInfo action must be sequenced after the InstallFiles action and the UnregisterProgIdInfo action.


RegisterTypeLibraries Action

The RegisterTypeLibraries action registers type libraries with the system. This action works on each file referred to in the TypeLib table that is triggered to be installed.

Database Tables Queried

TypeLib Table

Properties Used

None

Sequencing Restrictions

The RegisterTypeLibraries action must be sequenced after the InstallFiles action.


RegisterUser Action

The RegisterUser action registers the user information with the installer to identify the user of a product.

Database Tables Queried

None

Properties Used

The RegisterUser action uses the USERNAME, the COMPANYNAME, and the ProductID.

Sequencing Restrictions

None

Remarks

The RegisterUser action is not performed during an Admin install. If the Product ID entered by the user has not been validated by the ValidateProductID action, then the ProductID property will not be set and this action does nothing.


RemoveDuplicateFiles Action

The RemoveDuplicateFiles action deletes files installed by the DuplicateFiles action.

Database Tables Queried

DuplicateFile Table

Component Table

DuplicateFile.FileKey | Primary key, uniquely identifying an entry in the DuplicateFile table.
DuplicateFile.Component_ | Foreign key into the Component table.
DuplicateFile.File_ | Foreign key into the File table, referencing the file to be duplicated.
DuplicateFile.DestName | Name that was given to the duplicate file.
DuplicateFile.DestFolder | Property name whose value identifies the destination folder.

Properties Used

None

Sequencing Restrictions

The RemoveDuplicateFiles action must occur after the InstallValidate action and before the InstallFiles action.

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.


RemoveFiles Action

The RemoveFiles action uninstalls 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 whose components are resolved to the iisAbsent Action state (or the iisSource Action state if the component is currently installed locally) are removed.

The RemoveFiles action can also remove specific 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). This implies that removal of files specified in the RemoveFile table is attempted when the gating component is first installed, during a reinstall, and again when the gating component is removed.

The RemoveFiles action can also remove folders. You can indicate that a folder be removed if it is empty by leaving the FileName column of the RemoveFile table null.

Database Tables Queried

File Table

RemoveFile Table

Component Table

While uninstalling previously installed files, the database table fields queried are identical to those queried by the InstallFiles action (except that the Media table is not used at all by RemoveFiles).

While removing files specified in the RemoveFile table, the following fields are queried:

RemoveFile.FileName | Target file name (localized text).
RemoveFile.DirProperty | Property name that should resolve to a valid full directory path.
Component.Component | Unique name for the component item (text, primary key).
Component.Action | Enum indicating the action to be taken.

Properties Used

None

Sequencing Restrictions

The InstallValidate action must be called before calling RemoveFiles. If an InstallFiles action is used, it must appear after RemoveFiles.

Remarks

The RemoveFile table can be omitted from the install database if there are no miscellaneous files to remove.


RemoveFolders Action

The RemoveFolders action removes any folders linked to components set to be uninstalled or run from source. These folders are only removed if they are empty. If a folder is removed, it is unregistered with the appropriate component identifier.

Database Tables Queried

CreateFolder Table

Component Table

CreateFolder.Directory_ | Folder name. For each folder, a property is assumed to exist with this name that defines the folder location.
Component.ComponentId | Component ID for the component owning this folder.

Properties Used

Each folder name in the CreateFolder table is assumed to be a property defining the folder location.

Sequencing Restrictions

The RemoveFolders action must be executed after the RemoveFiles action or any action that may remove files from folders.


RemoveIniValues Action

The RemoveIniValues action deletes .ini file information that the application needs to delete from .ini files. The deletion of the information is gated by the Component table. A .ini value is deleted if the corresponding component has been set to be installed either locally or run from source.

Database Tables Queried

RemoveIniFile Table

Component Table

RemoveIniFile.FileName | The .ini file name in which the value is to be deleted.
RemoveIniFile.Directory_ | Directory for the .ini file. This is a foreign key into the Directory table.
RemoveIniFile.Section | The .ini file section.
RemoveIniFile.Key | The .ini file key under the section.
RemoveIniFile.Value | Value to be deleted.
RemoveIniFile.Action | How the value is to be deleted. For more information, see the IniFile table.
Component.Action Action field from the Component table for the component record corresponding to RemoveIniFile.Component_. Must be either:

iisLocal = 1: Item is to be installed locally (item is currently uninstalled or installed from run from source).

iisSource = 2: Item is to be installed from run from source (item is currently uninstalled or installed locally).

The RemoveIniValues action also removes the .ini information that the application writes to the system registry with the WriteIniValues action. A .ini value is deleted from the corresponding .ini file if the corresponding component has been set to be uninstalled.

IniFile Table

Component Table

IniFile.FileName | The .ini file name in which the value is written.
IniFile.Directory_ | Directory for the .ini file. This is a foreign key into the Directory table.
IniFile.Section | The .ini file section.
IniFile.Key | The .ini file key under the section.
IniFile.Value | Value that is written.
IniFile.Action | How the value is written. For more information, see the IniFile table. The RemoveIniValues action deletes the value that is written by reversing the IniFile.Action.
Component.Action | The Action field from the Component table for the component record corresponding to IniFile.Component_. Must be: iisAbsent = 0: Item is not installed.

Properties Used

None

Sequencing Restrictions

The InstallValidate action must be called before calling RemoveIniValues. If a WriteIniValues action is used, it must appear after RemoveIniValues.


RemoveRegistryValues Action

The RemoveRegistryValues action removes an application's registry information from the registry. A registry value is deleted from the registry if the corresponding component has been set to be installed locally or to run from source.

Database Tables Queried

Registry Table

RemoveRegistry Table

Component Table

RemoveRegistry.Root | Root key under which the registry value is written.
RemoveRegistry.Key | Key under the root.
RemoveRegistry.Name | Name of the value.
Component.Action Action field from the Component table for the component record corresponding to Registry.Component_. Must be either:

iisLocal = 1: Item is to be installed locally (item is currently uninstalled or installed from run from source).

iisSource = 2: Item is to be installed from run from source (item is currently uninstalled or installed locally).

The RemoveRegistryValues action also removes the registry information that the application writes to the registry with the WriteRegistryValues action. A registry value is deleted from the registry if the corresponding component has been set to be uninstalled.

Registry Table

Component Table

Registry.Root | Root key under which the registry value is written.
Registry.Key | Key under the root.
Registry.Value | The registry value to be removed. If the WriteRegistryValues action had attached REG_MULTI_SZ strings to the value in the Registry table, then the RemoveRegistryValues action removes only those strings from the registry value.
Registry.Name | Name of the value.
Component.Action | Action field from the Component table for the component record corresponding to Registry.Component_. Must be: iisAbsent = 0: item is not installed.

Properties Used

None

Sequencing Restrictions

The InstallValidate action must be called before calling RemoveRegistryValues. If a WriteRegistryValues action is used, it must appear after RemoveRegistryValues.


RemoveOldProducts Action

The RemoveOldProducts action removes old versions of a product that are already installed. The RemoveOldProducts action runs nested installs to remove old products.

Database Tables Queried

The RemoveOldProductsl action queries the Operator and Property columns of the Upgrade table. The value of the operator specifies whether the installed product version is removed.


RemoveShortcuts Action

The RemoveShortcuts action manages the removal of advertised shortcuts whose feature is selected for uninstall and non-advertised shortcuts whose component is selected for uninstall.

Database Tables Queried

Shortcut Table

Properties Used

None

Sequencing Restrictions

The RemoveShortcuts action must be sequenced after the InstallFiles action and before the CreateShortcuts action.


ResolveSource Action

The ResolveSource action will determine the source location and set the SOURCEDIR property if the source has not been resolved yet.

Database Tables Queried

None

Properties Used

SOURCEDIR

Sequencing Restrictions

This action must come after the CostInitialize action.


RMCCPSearch Action

The RMCCPSearch action uses file signatures to ensure that a user who acquires an upgrade version of a product has the installation for one of the qualifying upgrade products. The 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. The action works on the CCPSearch table.

Database Tables Queried

CCPSearch Table

CCPSearch.Signature_ File signature

Properties Used

CCP_DRIVE

CCP_Success

Sequencing Restrictions

None

Remarks

Each file signature, Signature_, in the 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 property CCP_Success is set to 1, and the RMCCPSearch action terminates.


ScheduleReboot Action

The ScheduleReboot action is authored in the sequence if there is a need to reboot at the end of the installation.

Database Tables Queried

None

Properties Used

None

Sequencing Restrictions

None. The ScheduleReboot action is typically placed at the end of the sequence, but it can be anywhere.


SelfRegModules Action

The SelfRegModules action processes all the modules in the SelfReg table to register the modules, if installed.

Database Tables Queried

The SelfRegModules action queries the File_ column of the SelfReg table for the module that is to be registered.

Properties Used

None

Sequencing Restrictions

The InstallValidate action must be called before calling SelfRegModules. If an InstallFiles action is used, it must also appear before SelfRegModules.

Remarks

The SelfRegModules action attempts to call the DllRegisterServer() function of the module that is to be registered. Unlike other actions, this action is not performed with elevated privileges but instead with the default user privileges.


SelfUnregModules Action

The SelfUnregModules action unregisters the modules in the SelfReg table that are to be uninstalled.

Database Tables Queried

The SelfUnregModules action queries the File_ column of the SelfReg table for the module that is to be unregistered.

Properties Used

None

Sequencing Restrictions

The InstallValidate action must come before the SelfUnregModules action. If a SelfRegModules action is used it must appear after the SelfUnregModules action. If a RemoveFiles action is used it must come after the SelfUnregModules action.

Remarks

The SelfUnregModules action attempts to call the DllUnregisterServer() function of the module that is to be unregistered. Unlike other actions this action is not performed with elevated privileges but instead is performed with the default user privileges.


SetODBCFolders Action

This action checks for ODBC drivers existing on the system and sets the target directory of each new driver to the location of an existing driver.

Database Tables Queried

This action sets the locations of existing drivers that are to be replaced in the Directory table.

Properties Used

None.

Sequencing Restrictions

The SetODBCFolders action must come after the CostFinalize action and before the InstallValidate action.

Remarks

This action places a new driver into the same directory as the existing driver being replaced.


UnpublishComponents Action

The UnpublishComponents action manages the unadvertisement of the components from the PublishComponent table that may be faulted in by other products with the system. This action removes the information about published components from the PublishComponent table for which the corresponding feature is currently selected to be uninstalled.

Database Tables Queried

PublishComponent Table

Properties Used

None

Sequencing Restrictions

None


UnpublishFeatures Action

The UnpublishFeatures action manages the unadvertisement of the feature composition (feature-component mapping) with the system. This action removes the published composition of all features that are currently selected to be uninstalled.

Database Tables Queried

FeatureComponents Table

Properties Used

None

Sequencing Restrictions

None


UnregisterClassInfo Action

The UnregisterClassInfo action manages the unregistration of COM class information with the system. The action unregisters the COM classes from the Class table for which the corresponding feature is currently selected to be uninstalled.

Database Tables Queried

Class Table

Properties Used

None

Sequencing Restrictions

The UnregisterClassInfo action must be sequenced after the InstallFiles action and before the RegisterClassInfo action.


UnregisterExtensionInfo Action

The UnregisterExtensionInfo action manages the unregistration of extension-related information with the system. The action unregisters the extension servers from the Extension table for which the corresponding feature is currently selected to be uninstalled.

Database Tables Queried

Extension Table

Verb Table

Component Table

Properties Used

None

Sequencing Restrictions

The UnregisterExtensionInfo action must be sequenced after the InstallFiles action and before the RegisterExtensionInfo action.


UnregisterFonts Action

The UnregisterFonts action unregisters installed fonts with the system. The RegisterFonts action is triggered when the component to which the Font.File belongs is selected for uninstall. This implies that fonts can be made private, shared, or available to the entire system by specifying such status for the components to which they belong.

Database Tables Queried

Font Table

File Table

Component Table

Properties Used

None

Sequencing Restrictions

The RemoveFiles action must be called after UnregisterFonts.


UnregisterMIMEInfo Action

The UnregisterMIMEInfo action unregisters MIME-related registry information from the system. The action unregisters MIME info for servers from the MIME table for which the corresponding feature is currently selected to be uninstalled.

Database Tables Queried

MIME Table

Properties Used

None

Sequencing Restrictions

The UnregisterMIMEInfo action must be sequenced after the InstallFiles action and before the RegisterMIMEInfo action.


UnregisterProgIdInfo Action

The UnregisterProgIdInfo action manages the unregistration of OLE ProgId information with the system. This action unregisters ProgId information for features that are connected to the extension information (in the Extension table) or the Class information (in the Class table and are currently selected to be uninstalled.

Database Tables Queried

ProgId Table

Class Table

Extension Table

Properties Used

None

Sequencing Restrictions

The UnregisterProgIdInfo action must be sequenced after the InstallFiles action and before the RegisterProgIdInfo action.


UnregisterTypeLibraries Action

The UnregisterTypeLibraries action unregisters type libraries from the system. This action works on each file referred to in the TypeLib table that is triggered to be uninstalled.

Database Tables Queried

TypeLib Table

Properties Used

None

Sequencing Restrictions

The UnregisterTypeLibraries action must be sequenced before the RemoveFiles action.


UpdateResources Action

The UpdateResources action copies text or binary data into file resources.

Database Tables Queried

File Table

Resource Table

Component Table

Properties Used

Only properties specified in the data string.

Sequencing Restrictions

The UpdateResources action must be sequenced after the InstallFiles action.

Remarks

If the data string contains property parameters (that is, the property names within square brackets), the current values for those properties are substituted. If the resultant string begins with 0x, the string is treated as a hexadecimal value, and the resource is updated with the binary value.


ValidateProductID Action

The ValidateProductID action sets the ProductID property to the full Product ID. If the Product ID has already been validated successfully, then this action does nothing.

Properties Used

The ValidateProductID action performs Product ID validation by comparing the PIDKEY property to the PIDTemplate property.

Sequencing Restrictions

This action must be included in the sequence tables. The action must come before the UI wizard in the InstallUISequence table and before the RegisterUser action in the InstallExecuteSequence table.

Remarks

The ValidateProductId action always returns a success, whether or not the Product ID is valid, so that the product ID can be entered the on the command line the first time the product is run.

The Product ID can be validated without having the user reenter this information by setting the PIDKEY property on the command line or by a transform. The display requesting the user to enter the Product ID can then be made conditional upon the presence of the ProductID property, which is set when the PIDKEY property is validated.


WriteIniValues Action

The WriteIniValues action writes .ini file information that the application needs to write in .ini files. The writing of the information is gated by the Component table. A .ini value is written if the corresponding component has been set to be installed either locally or run from source.

Database Tables Queried

IniFile Table

Component Table

IniFile.FileName | The .ini file name in which the value is written.
IniFile.Directory_ | Directory for the .ini file. This is a foreign key into the Directory table.
IniFile.Section | The .ini file section.
IniFile.Key | The .ini file key under the section.
IniFile.Value | Value to be written.
IniFile.Action | How the value is to be written. For more information, see the IniFile table.
Component.Action Action field from the Component table for the component record corresponding to IniFile.Component_. Must be either:

iisLocal = 1: Item is to be installed locally (item is currently uninstalled or installed from run from source).

iisSource = 2: Item is to be installed from run from source (item is currently uninstalled or installed locally).

Properties Used

None

Sequencing 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.


WriteRegistryValues Action

The WriteRegistryValues action sets up registry information that the application needs in the registry. 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 run from source.

Database Tables Queried

Registry Table

Component Table

Registry.Root | Root key under which the registry value is written.
Registry.Key | Key under the root.
Registry.Name | Name of the value.
Registry.Value | The registry value.
Component.Action Action field from the Component table for the component record corresponding to Registry.Component_. Must be either:

iisLocal = 1: Item is to be installed locally (item is currently uninstalled or installed from run from source).

iisSource = 2: Item is to be installed from run from source (item is currently uninstalled or installed locally).

Properties Used

None

Sequencing Restrictions

The InstallValidate action must come before the WriteRegistryValues action. If there is a RemoveRegistryValues action, then it must come before the WriteRegistryValues action.


Custom Actions

The Microsoft® Windows® installer provides a number of actions to be used during the install process. For a list of these actions see Standard Actions Reference. For most situations these actions are sufficient. However, 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.

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 installer. For general information on the installer, see About Windows Installer.

The topics in this section describe how to incorporate custom actions into an installation package. The topics include

  • About Custom Actions
  • Using Custom Actions
  • Custom Action Reference


About Custom Actions

The following sections give general information about custom actions

  • Invoking Custom Actions
  • Synchronous and Asynchronous Custom Actions
  • Executable Files
  • Dynamic Link Libraries
  • Scripts
  • Formatted Text
  • Custom Action Security
  • Deferred Execution of Custom Actions
  • Rollback of Custom Actions
  • Information for Custom Actions
  • Debugging Custom Actions


Invoking Custom Actions

There are two processes for calling actions. The action can be either a custom action or a standard action.

  • A top-level action calls the sequence table to which the specified action belongs.
  • You call the specified action directly with the MsiDoAction function.

When the installer obtains an action name from the MsiDoAction function or from a sequence table, it searches for a standard action of that name. If it cannot find the standard action, 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, the installer queries the Dialog table for a dialog box to present. This dialog box typically starts a wizard sequence.


Synchronous and Asynchronous Custom Actions

Custom actions that are implemented as a DLL or an EXE can be invoked either synchronously or asynchronously. For a synchronous process, the installer waits for the action to complete before installation continues. For an asynchronous process, the custom action runs as a separate thread while installation continues.


Executable Files

The installer calls executables by creating a separate process at user privilege. Executable custom actions cannot return the full set of return values described in Custom Action Return Values. They can only indicate success or failure. Synchronous calls returning a non-zero status cause the installation to terminate.

The following options can be specified for an executable custom action as described in Custom Action Types.

The executable file can be:

  • Known to exist on the system
  • Installed during this session
  • Stored in the Binary table

The custom action author can also specify whether the action will be run synchronously or asynchronously. Custom actions can also be scheduled to run during install script processing or during rollback as described in Deferred Execution of Custom Actions.

Command line parameters can be passed in the Target column of the CustomAction table.


Dynamic-Link Libraries

The installer calls dynamic link libraries by creating a separate thread at user privilege. The installer calls the DLL with the handle to the current session as the only parameter. DLL custom actions return the full set of return values described in Custom Action Return Values.

You can call DLLs through the entry point named in the Target column of the CustomAction table. The entry point name specified in the table must exactly match the entry point exported from the DLL.

The following options can be specified for a DLL custom action as described in Custom Action Types.

The DLL can be:

  • Installed during this session
  • Stored in the Binary table

The custom action author can specify whether the action will be run synchronously or asynchronously. Custom actions can also be scheduled to run during install script processing or during rollback as described in Deferred Execution of Custom Actions.


Scripts

The installer calls scripts by creating a separate process at user privilege. Script custom actions return the full set of return values described in Custom Action Return Values. The installer does not provide the script engine but can use it if it is installed. Authors wishing to make use of a scripting language during installation should be certain that the appropriate scripting engine is available.

The following options can be specified for a script custom action as described in Custom Action Types.

The script file can be:

  • Installed during this session
  • Stored in the Binary table
  • Stored in a property value
  • Stored in Target column of the CustomAction table.

Script custom actions can only be executed synchronously. Custom actions can be scheduled to run during rollback as described in Deferred Execution of Custom Actions.


Formatted Text

Custom actions can be used to set properties and directories with formatted text. This can be useful for passing information to other custom actions. For information on how to specify set properties and directories with formatted text, see Custom Action Types. For information on how to format text, see the Formatted data type.


Custom Action Security

Custom actions run at user privileges and have limited access to the system. Custom actions can access the system for queries, but all updates are passed through a security boundary for subsequent execution, as described in Installation Mechanism.

The only way a custom action can cause a change at elevated privileges is by manipulating tables used by built-in actions.


Deferred Execution of Custom Actions

Custom actions can be scheduled to run during any of the various phases of the install process. For more information about the phases of an installation, see Installation Mechanism.

If a custom action only sets properties, sets directories, or manipulates the installation database, then it should be scheduled to run during the acquisition phase when the database is processed. However, if a custom action performs any system changes directly, it should be scheduled to run during the execution stage when the install script is processed.

The installer does not provide the script engine but can use it if it is installed. Authors wishing to make use of a scripting language during installation should be certain that the appropriate scripting engine is available.

There are special restrictions that apply to deferred custom actions. See Information for Custom Actions for more information.

You can also schedule custom actions to run during rollback. This is described in more detail in Rollback of Custom Actions.


Rollback of Custom Actions

Custom actions that schedule system operations by inserting rows into the appropriate tables are automatically rolled back if the installation is unsuccessful. However, if a custom action performs operations on its own or issues commands to other services, these operations or commands cannot be automatically rolled back. You must provide a custom action that performs the necessary operations during rollback processing.

A rollback custom action is designated as described in Custom Action Types. When this action is invoked during the installation sequence, its execution is deferred until rollback as described in Deferred Execution of Custom Actions.


Information for Custom Actions

Custom actions obtain information about the current install by using the database access functions. A custom action can obtain a handle to the active database. This handle allows the custom action to query and update the data in the various tables. Some data might be marked as read-only and cannot be updated by actions.

Arguments cannot be passed to custom actions. They must obtain information by querying properties, tables, and session state flags. To effect argument passing, custom actions can set properties used by subsequent custom actions. Using a custom action that sets a property with formatted text is an efficient method to accomplish this.

If a custom action is scheduled to run during script processing as described in Deferred Execution of Custom Actions, the action may be run outside of an install session. Very little information is available to such custom actions. Therefore, the context information must be set beforehand. The command line for an EXE custom action is stored in the install script, so any information the custom action needs should be indicated in the command line.

A DLL custom action receives an install session handle. During script execution, the session may not exist. However, the following functions that require a handle are supported during script processing.

Function | Functionality during script processing
MsiGetProperty | Supports only ProductCode and CustomActionData. Others return NULL.
MsiGetMode | Indicates the installation mode.
MsiGetLanguage | Returns the numeric language ID for the current product.
MsiProcessMessage | Processes messages from the custom action.

In addition, any function that does not require a session handle is supported.

Except for the properties mentioned in the table above, properties are not available to deferred custom actions. To provide further context information to your custom action, use the CustomActionData property. Put any information you want to pass to the custom action in a property with the same name as the custom action. For example, if the primary key for a custom action entry is named MyAction, set the MyAction property with any needed contextual information. You can then gain access to this information from within the custom action by calling MsiGetProperty with CustomActionData as the property identifier.

One way to set the CustomActionData is with a Formatted Text custom action.

A script custom action receives the install session object, but has the same restrictions that a DLL custom action has. For example, the install session object may not exist if the action is deferred. A few methods are supported to allow the custom action to retrieve its context. The Mode property returns TRUE for only imfOperations. The Property Property (MsiEngine Object) returns properties as described above. The Language Property (MsiEngine Object) is available. And the Message method can be called to handle errors.


Debugging Custom Actions

To enable the debugging of a custom action, set the environment variable MsiBreak to the name of the designated action. 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 Just In Time debugging.

To enable source-level debugging, the program database (PDB) file must be available, either at the original build location for the DLL or in the directory where the DLL is now running. Custom actions stored in the Binary table are executed from the system Temp directory. 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.


Using Custom Actions

To be written


Custom Action Reference

The following reference sections pertain to custom actions.

  • For information about what values your custom actions are expected to return, see Custom Action Return Values
  • For information about how to indicate the type of custom action see Custom Action Types
  • Custom actions typically access the installation database. See the Database Access Reference topic for a list of functions that work with the database.


Custom Action Return Values

Your custom actions must return the following values. These return values determine the course for further execution. DLL and script actions return the full set of return values. EXE processes and the setting of directories from formatted text can only indicate success or failure return values.

Return value | Description
ERROR_FUNCTION_NOT_CALLED | Action is not found.
ERROR_SUCCESS | Action is completed successfully.
ERROR_INSTALL_USEREXIT | User terminates the action during the action execution.
ERROR_INSTALL_FAILURE | Action fails.
ERROR_INSTALL_SUSPEND | User suspends the installation.
ERROR_MORE_DATA | Action skips remaining actions; not an error.
ERROR_INVALID_HANDLE_STATE | Installation session is not active.
ERROR_INVALID_DATA | Call to custom action fails.
ERROR_INVALID_HANDLE | Arguments are invalid.
ERROR_INVALID_PARAMETER | Arguments are invalid.


Custom Action Types

The custom action type is specified by a numeric value in the Type column of the CustomAction table. The following tables describe how to indicate the type.

Formatted Text

The following table describes the values as well as the meaning of the Source and Target columns of the CustomAction table for these types of custom actions. A custom action that sets a property or directory with formatted text cannot use the options described in subsequent tables.

Numeric Value | Description | Source | Target
51 | Property set with formatted text | Property name | String to be formatted
35 | Directory set with formatted text | Key into the Directory table | String to be formatted

Executable, DLL, or Script

A custom action can also be an executable file, a dynamic-link library, or a script. These custom actions are composed of a source type, an executable type, and option flags. To indicate these types, select one number from each of the following tables, add the values together, and enter the resulting number in the Type column of the CustomAction table. Note that the meanings of the other columns in the CustomAction table vary depending on the options. See the table describing the Location options for more information.

The installer does not provide the script engine but can use it if it is installed. Authors wishing to make use of a scripting language during installation should be certain that the appropriate scripting engine is available.

Source Type

The following table describes the action type options.

Numeric Value | Description
1 | The action is a DLL.
2 | The action is an .exe file.
5 | The action is Microsoft® JScript™, source.
6 | The action is Microsoft® Visual Basic® Scripting Edition (VBScript) source.

Location

The following table shows the custom action source options along with the corresponding meanings of the Source and Target columns of the CustomAction table. If an entry in the table is blank, it is the same as the entry directly above it.

Numeric Value | Description | Source | Target
0 | The data is stored in the Binary table. | Key into the Binary table. | For a DLL; the DLL entry point.
 |  |  | For an EXE; the command line options.
 |  |  | For a script; an optional function to call.
16 | The file is copied during installation. The file is listed in the File table. | Key into the File table. | Same as for a source option of 0.
32 | For an EXE file, the location of the folder containing the existing file is given in the Directory table. | Key into the Directory table. | The executable name and command line options.
 | For a script, the script itself is stored in the Target column of the CustomAction table. | Null | The script source.
 | Not allowed for a DLL. |  |
48 | For an EXE file, a property holds the full path to the executable. | Property name, key into the Property table. | Same as for a source option of 0.
 | For a script, the property holds the source of the script itself. |  |
 | Not allowed for a DLL. |  |

Synchronous or Asynchronous Execution

The following table describes the custom action processing options.

Numeric Value | Description
0 | Synchronous execution; must return exit code.
64 | Synchronous execution; exit code is ignored.
128 | Asynchronous execution; wait for exit code at sequence end.
192 | Asynchronous execution; wait for exit code at install termination.

Scheduling Options

The following table describes the custom action scheduling options.

Numeric Value | Description
0 | Run action when the installer reaches it during database processing.
256 | Run action at the appropriate stage during install script processing.
512 | Run action only during install rollback.


Properties

The following sections describe properties used in the Microsoft® Windows® installer.

  • About Properties briefly describes what properties are and what they can be used for.
  • Using Properties shows a couple of simple examples of how properties can be used.


About Properties

Properties are global variables used during an installation. All the properties are listed in the Property table of the installation database. Any property can be specified in the property table and will then be set at the launch of the installation. In addition, some properties are public and can be overridden at the command line or set dynamically during the installation using Standard actions or Custom actions. The names of public properties are always in all uppercase letters. Private property names are specified in the Property table and cannot be overridden because they describe the local system or operating system. For example, it is possible to author a package in which the public INSTALLLEVEL property is specified at the command line or chosen in a user interface. The WindowsFolder property however is set for the Windows platform. This property is specified in the Property table and cannot be overridden by an action or the command line. For more information on the individual properties see the Property Reference topic.


Using Properties

Typically properties are used in conditional expressions in the database to convey additional installation logic. For example, the Feature table is linked to the Condition table. This can be used to indicate if a feature should be installed depending upon the values of one or more properties.

Similarly, in the six sequence tables, there is a column for a conditional expression. A dialog listed in a sequence table with Installed AND NOT Resume AND NOT Preselected in the condition column would only display if all of the following conditions were met.

  • The product is already installed.
  • The installation session is not resuming a partially completed install.
  • The needed options were not already set on the command line when the installation was initiated.

This would be useful for a maintenance dialog.

The full syntax for conditional expressions is described in MsiEvaluateCondition.

For more examples of using properties see Using a Sequence Table.


Property Reference

The following properties are defined by the Microsoft® Windows® installer. Additional properties can be specified by authored data or custom actions. Properties whose names are entirely uppercase can be specified on the command line.

The following list provides links to more information about the component locations properties:

SOURCEDIR Property
TARGETDIR Property

The following list provides links to more information about the feature installation options properties:

ADDLOCAL Property
ADVERTISE Property
ADDDEFAULT Property
ADDSOURCE Property
REMOVE Property
REINSTALL Property
COMPADDLOCAL Property
COMPADDSOURCE Property
FILEADDLOCAL Property
FILEADDSOURCE Property
PATCH Property

The following list provides links to more information about other configurable properties:

ACTION Property
ALLUSERS Property
ALLOWSUSPEND Property
ARPNOMODIFY Property
ARPNOREMOVE Property
CCP_DRIVE Property
EXECUTEACTION Property
EXECUTEMODE Property
INSTALLLEVEL Property
LOGACTION Property
LOGFILE Property
LOGMODE Property
REBOOT Property
ROOTDRIVE Property
SCRIPTFILE Property
SHORTFILENAMES Property
TRANSFORMS Property
LIMITUI Property

The following list provides links to more information about user-supplied information.

AdminProperties Property
COMPANYNAME Property
ProductID Property
PIDKEY Property
USERNAME Property
PRODUCTLANGUAGE Property

The following list provides links to more information about product-specific properties specified in the property table:

ProductCode Property
ProductName Property
ProductVersion Property
Manufacturer Property
PIDTemplate Property
DiskPrompt Property
DiskSerial Property
ComponentDownload Property
SupportPhone Property
SupportURL Property
LeftUnit Property
UpgradeCode Property

The following list provides links to more information about system folders set by the installer at setup.

AppDataFolder Property
CommonFilesFolder Property
DesktopFolder Property
FavoritesFolder Property
FontsFolder Property
NetHoodFolder Property
PersonalFolder Property
PrintHoodFolder Property
ProgramFilesFolder Property
ProgramMenuFolder Property
RecentFolder Property
SendToFolder Property
StartMenuFolder Property
StartupFolder Property
System16Folder Property
SystemFolder Property
TempFolder Property
TemplateFolder Property
WindowsFolder Property
WindowsVolume Property

The following list provides links to more information about operating system properties set by the installer at startup.

AdminUser Property
ComputerName Property
LogonUser Property
ServicePackLevel Property
SharedWindows Property
Version9X Property
VersionDatabase Property
VersionNT Property
WindowsBuild Property

The following list provides links to more information about hardware properties set by the installer at startup.

Alpha Property
BorderSide Property
BorderTop Property
CaptionHeight Property
ColorBits Property
Intel Property
PhysicalMemory Property
ScreenX Property
ScreenY Property
TextHeight Property
VirtualMemory Property

The following list provides links to more information about status properties that are updated by the installer during installation.


ACTION Property

Specifies the initial action function that is called after the installer. in initialized.

Set By

Set on the command line. Normally set to INSTALL, ADVERTISE or ADMIN. If not set, the INSTALL action will be called.

Used By

After the installer is successfully initialized, Action uses this value to determine the type of action invoked . That action will most likely invoke other actions, commonly by querying the Action table.

Default Value

None. If not set the INSTALL Action will be called.


ADVERTISE Property

The property value denotes a list of features, delimited by commas, that are to be advertised. The features listed are to be found in the Feature column of the Feature table. Optionally, the value could be All to denote advertising all. Thus, if you wish to install all features locally you would provide the command line ADVERTISE=All to the installer.

Set By

Command line.

Used By

MsiEngine uses this value to determine if a feature is advertised.

Default Value

None.

Remarks

Note that the feature names are case-sensitive.


ADDDEFAULT Property

The property value denotes a list of features, delimited by commas, that are to be installed in their default configuration. The features listed are to be found in the Feature column of the Feature table. Optionally, the value could be All. Thus, if you wish to install all to their default configuration you would provide the command line ADDDEFAULT=All to the installer.

Set By

Command line.

Used By

MsiEngine uses this value to determine which features are advertised.

Default Value

None.

Remarks

Note that the feature names are case-sensitive.


ADDLOCAL Property

The property value denotes a list of features, delimited by commas, that are to be installed locally. The features listed are to be found in the Feature column of the Feature table. Optionally, the value could be All to denote installing all features locally. Thus, if you wish to install all features locally you would provide the command line ADDLOCAL=All to the installer.

Set By

Command line.

Used By

MsiEngine uses this value to determine which features are to be installed locally.

Default Value

None.

Remarks

Note that the feature names are case-sensitive. Also note that if the RunFromSource column of the Component table for a component has a value of irsSourceOnly then the component is installed as run from source.


ADDSOURCE Property

The property value denotes a list of features, delimited by commas, that are to be installed to run from source. The features listed are to be found in the Feature column of the Feature table. Optionally, the value could be All to denote installing all features to run from source. Thus, if you wish to install all features as run from source you would provide the command line ADDSOURCE=All to the installer.

Set By

Command line.

Used By

MsiEngine uses this value to determine which features are to be installed as run from source.

Default Value

None.

Remarks

Note that the feature names are case-sensitive. Also note that if the RunFromSource column of the Component table for a component has a value of irsLocalOnly then the component is installed locally.


AdminProperties Property

The AdminProperties property is a semicolon delimited list of properties set at the time of an administration installation. During the post administration installation of the application these properties replace the current values in the installer database.

Set By

The AdminProperties property list should be defined by the author and then set based upon information collected by the user interface during the network installation.

Used By

The installer uses this value to set administration property values.

Default Value

The values of properties already in the installer database.

Remarks

The property names in the list can be internal or external (all uppercase) properties. For example, AdminProperties values could be INSTALLLEVEL, PIDKEY, or the user's name and company.


AdminUser Property

The AdminUser property is set on Windows NT whenever the user has administrator privileges. By convention, this property is always set on Windows 95 and Windows 98.

Set By

Installer at initialization.

Used By

Typically, the user is asked if this will be a per-user or per-machine installation.

Default Value

None.


ALLOWSUSPEND Property

Setting this property gives the user the option to continue at a later time a failed or cancelled installation or to do a rollback of the installation. This choice is presented to the user in the form of an error dialog box displayed before the final exit dialog box.

Set By

Command line, or authored into the Property table.

Used By

Default Value

If ALLOWSUSPEND is not set, the default is to not display the dialog box following a failed or cancelled install and to do a rollback of the installation.

Remarks

As with all error message dialogs, the suspend option dialog box will display even with a basic UI.


ALLUSERS Property

If this property is set, the folder properties representing folders in a profile are set to the folders in the "All Users" profile, if such a profile exists. Otherwise, those properties are set to folders in the user's personal profile.

Set By

Command line.

Used By

Default Value

None. May be undefined.

Remarks

None.


Alpha Property

Defined only if running on an Alpha processor. The value is the numeric processor level.

Set By

Installer at initialization.

Used By

Actions and condition expressions.

Default Value

None.


AppDataFolder Property

Full path to the Application Data folder for the current user. Set for Windows NT but not for Windows 95 and Windows 98.

Set By

Installer at initialization.

Used By

Actions and Directory table.

Default Value

None.

Remarks

A common value for this property is C:\Winnt\Profiles\[LogonUser]\Application Data\.


ARPNOMODIFY Property

The ARPNOMODIFY property disables Add/Remove Control Panel and Programs Wizard functionality that would modify the product. If the property is set, RegisterProduct action writes the value for do not modify under the Uninstall key and prevents the UninstallString from being written to the registry.

Set By

The ARPNOMODIFY property is set in the Property table by authoring directly or through the use of a transform.

Used By

RegisterProduct.

Default Value

None.

Remarks

For example, this property can be set during a customization transform to prevent users from changing an administrator customization.


ARPNOREMOVE Property

The ARPNOREMOVE property disables the Add/Remove Control Panel and Programs Wizard functionality that would remove the product. If the property is set, RegisterProduct action writes the value for do not remove under the Uninstall key and prevents the UninstallString from being written to the registry.

Set By

The ARPNOREMOVE property is set in the Property table by authoring directly or through the use of a transform.

Used By

RegisterProduct.

Default Value

None.

Remarks

For example, this property can be set during a customization transform to prevent users from removing an administrator customization.


BorderSide Property

The width, in pixels, of the window borders.

Set By

Installer at initialization.

Used By

Actions and condition expressions.

Default Value

None.

Remarks

None.


BorderTop Property

The height, in pixels, of the window borders.

Set By

Installer at initialization.

Used By

Actions and condition expressions.

Default Value

None.

Remarks

None.


CaptionHeight Property

Height, in pixels, of normal caption area.

Set By

Installer at initialization.

Used By

Actions and condition expressions.

Default Value

None.

Remarks

None.


CCP_DRIVE Property

Property to be set to the root path on the removable volume that has the installation for any of the qualifying products for CCP.

Set By

Property table, command line or through the UI.

Used By

RMCCPSearch.

Default Value

None.

Remarks

None.


ColorBits Property

Number of adjacent color bits for each pixel.

Set By

Installer at initialization.

Used By

Actions and condition expressions.

Default Value

None.

Remarks

None.


CommonFilesFolder Property

Full path to the Common Files folder for the current user.

Set By

Installer at initialization.

Used By

Actions and Directory table.

Default Value

None.

Remarks

A common value for this property is C:\Program Files\Common Files\.


COMPADDLOCAL Property

The property value denotes a list of component ID's, delimited by commas, that are to be installed locally. Specifically, for each listed component ID, the installer examines all features linked (via the FeatureComponents table) to that component, and installs the "cheapest" feature (i.e. the feature that would require the least amount of disk space to install). The components listed are to be found in the Component column of the Component table.

Set By

Command line.

Used By

MsiEngine uses this value to determine which feature(s) are set to be installed locally, based on the specified component(s).

Default Value

None.

Remarks

Note that the component names are case-sensitive. Also note that if the RunFromSource column of the Component table for a component has a value of irsSourceOnly then the component will be installed to run from source.


COMPADDSOURCE Property

The property value denotes a list of component ID's, delimited by commas, that are to be installed to run from the source media. Specifically, for each listed component ID, the installer examines all features linked (via the FeatureComponents table) to that component, and installs the "cheapest" feature (i.e. the feature that would require the least amount of disk space to install). The components listed are to be found in the Component column of the Component table.

Set By

Command line.

Used By

MsiEngine uses this value to determine which feature(s) are set to be installed to run from source, based on the specified component(s).

Default Value

None.

Remarks

Note that the component names are case-sensitive. Also note that if the RunFromSource column of the Component table for a component has a value of irsLocalOnly then the component will be installed to run locally.


COMPANYNAME Property

Organization for user performing the installation.

Set By

Set by registry properties, can be overridden on command line.

Used By

UI dialogs and ultimately, personalization actions.

Default Value

None.


ComponentDownload Property

URL for downloading components by ID (string GUID).

Set By

Authored into Property table. Optional.

Used By

Installer uses this value to request a component when it is not possible to connect to any product source (server or CD).

Default Value

None.


ComputerName Property

The computer name of the current system.

Set By

Installer at initialization. Set by system call GetComputerName().

Used By

Actions and conditional expressions.

Default Value

None.


CostingComplete Property

The CostingComplete property is used to indicate whether the installer has completed disk space costing.

Set By

The CostingComplete 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.

Used By

This property can be used to author a dialog box that pops up if costing has not been completed.

Default Value

None.

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..


VersionDatabase Property

The value is the numeric database version of the current installation.

Set By

Installer at initialization.

Used By

Actions and condition expressions.

Default Value

None.


DesktopFolder Property

Full path to the Desktop 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.

Set By

Installer at initialization.

Used By

Actions and Directory table.

Default Value

None.

Remarks

Common values for this property are C:\Winnt\Profiles\[LogonUser]\Desktop\ (Windows NT) and C:\Windows\Desktop\ (Windows 95 and Windows 98).


DiskPrompt Property

The string displayed by a message box prompting for a disk. This string should include the name of the product and a placeholder for the text printed on the CD surface. See Authoring Disk Prompt Messages.

Set By

Authored into the Property table.

Used By

Advertised as a product property. Used to display Diskprompt dialog when a disk is not detected in any drive.

Default Value

None.


DiskSerial Property

The internal serial number for the CD for this particular product release.

Set By

Authored into Property table. Required if a CD product.

Used By

Advertised as a product property. Used to locate the CD in any drive.

Default Value

None.


EXECUTEACTION Property

The EXECUTEACTION Property is set to determine which top-level action the ExecuteAction action initiates.

Set By

The top-level actions, such as the INSTALL action, ADVERTISE action, and Advertise action, set the EXECUTEACTION property to the name of the top-level action.

Used By

ExecuteAction.


EXECUTEMODE Property

This property indicates the mode of execution performed by the installer. This property can have one of two values:

None
No changes are made to the system. The installer does execute the user interface and the queries the database.
Script
All changes to the system are made through script execution. This is the default mode.

Set By

Command line.

Used By

The installer uses this property to determine how system updates are executed.

Default Value

If this property is not defined, then the execution mode defaults to Script.

Remarks

The installer only examines the first letter of this property value and is case insensitive.


FavoritesFolder Property

Full path to the Favorites folder for the current user.

Set By

Installer at initialization.

Used By

Actions and Directory table.

Default Value

None.

Remarks

Common values for this property are C:\Winnt\Profiles\[LogonUser]\Favorites\ (Windows NT) and C:\Windows\Favorites\ (Windows 95 and Windows 98).


FILEADDLOCAL Property

The property value denotes a list of file keys, delimited by commas, that are to be installed to run locally. Specifically, for each listed file key, the installer determines the component that controls that file, then examines all features linked (via the FeatureComponents table) to that component, and installs the "cheapest" feature (i.e. the feature that would require the least amount of disk space to install). The file keys listed must be found in the File column of the File table.

Set By

Command line.

Used By

MsiEngine uses this value to determine which feature(s) will be installed locally, based on the specified file key(s).

Default Value

None.

Remarks

Note that the file key names are case-sensitive. Also note that if the RunFromSource column of the Component table for a component has a value of irsSourceOnly then the component will be installed to run from source.


FILEADDSOURCE Property

The property value denotes a list of file keys, delimited by commas, that are to be installed to run from the source media. Specifically, for each listed file key, the installer determines the component that controls that file, then examines all features linked (via the FeatureComponents table) to that component, and installs the "cheapest" feature (i.e. the feature that would require the least amount of disk space to install). The file keys listed must be found in the File column of the File table.

Set By

Command line.

Used By

MsiEngine uses this property to determine which feature(s) will be installed to run from source, based on the specified file key(s).

Default Value

None.

Remarks

Note that the file key names are case-sensitive. Also note that if the RunFromSource column of the Component table for a component has a value of irsLocalOnly then the component will be installed to run locally.


FontsFolder Property

Full path to the Fonts folder.

Set By

Installer at initialization.

Used By

Actions and Directory table.

Default Value

None.

Remarks

A common value for this property is [WindowsFolder]Fonts.


Installed Property

The Installed property indicates that a product is already installed.

Set By

This property is set by the Installer at initialization if the product is already installed.

Used By

The Installed property can be used in conditional expressions to determine if a product is already installed. For example, the property can be used in the conditional column of a sequence table or to differentiate between a first install and maintenance mode user interface.

Default Value

None.


INSTALLLEVEL Property

The initial 'level' at which features will be selected 'ON' for installation by default. See the Feature table for further discussion of install levels.

Set By

Property table.

Used By

Selection resolution actions.

Default Value

If no value is specified, the install level defaults to 1.


Intel Property

Defined only if running on an Intel processor. The value is the numeric processor level, i.e. 4 for 486, 5 for P5, 6 for P6, etc..

Set By

Installer at initialization.

Used By

Actions and condition expressions.

Default Value

None.


LeftUnit Property

If this property is set, the unit is placed to the left of the number instead of the usual right hand side. This is needed to accommodate languages where this is the accepted format.

Set By

The value is set in the Property Table.

Used By

The UI uses this property to display the size of files and the available space on different volumes.

Default Value

None.

Remarks

!!Additional notes!!


LOGACTION Property

A list of action names, separated only by semicolons (no spaces), for which logging will occur.

Set By

Command line.

Used By

MsiEngine.Message uses this property to determine which actions will generate log information.

Default Value

None.

Remarks

The action names in this property are case-insensitive. The list may optionally end with a semicolon.


LOGFILE Property

Enables logging of messages by specifying a path to the file where the log information is to be written. The file will be created if not present, else any old log information from a previous installation will be overwritten unless the append option is set by the LOGMODE property. The logfile is flushed after each line is posted, and it is closed when the MsiServices object is destroyed.

Set By

Set on the command line.

Used By

The installer uses this property to specify which log file will be opened when the installer is initialized. Initialization will fail if the log file cannot be opened.

Default Value

None.

Remarks

The first line of the log will be formatted according to the value of the imgLogHeader entry in the Error table. Log line formats are determined by the various message and action types, as well by code that directly writes directly to the log. The final line of the log will be formatted according to the value of the imsgLogTrailer entry in the Error table. For an example of using the LOGFILE property, see Command Line Options.


LOGMODE Property

A string containing letters that specify which messages are to be written to the log file. Options are case-insensitive and order-independent.

Set By

Command line.

Used By

MsiEngine uses this value to initialize logging for the various message types, but only if the LOGFILE property is defined.

Default Value

None. Internal default log options, "ewarim", are used if this property is undefined.

Log Option Codes - for message types:

i | (imtInfo) | Informational-only messages
w | (imtWarning) | Warning messages, not fatal
e | (imtError) | Error messages, may be fatal
f | (imtFilesInUse) | List of files in use that need to be replaced
a | (imtActionStart) | Start of action notification
r | (imtActionData) | Action data record, contents action-specific
u | (imtUser) | User request messages
c | (imtCommonData) | Common Data messages
m | (imtOutOfMemory) | Out of memory messages
p |  | Dump property table, "property = value" at MsiEngine.Terminate
+ |  | Append to existing logfile

For an example of using the LOGMODE property, see Command Line Options.


LogonUser Property

The user name for the currently logged on user.

Set By

Installer at initialization. Set by system call GetUserName().

Used By

Actions and conditional expressions.

Default Value

None.

Remarks

None.


Manufacturer Property

The name of the manufacturer for the product.

Set By

Authored into Property table. REQUIRED.

Used By

Advertised as a product property.

Default Value

None.


NetHoodFolder Property

Full path to the NetHood (Network Neighborhood) folder for the current user. Set for Windows NT but not for Windows 95 and Windows 98.

Set By

Installer at initialization.

Used By

Actions and Directory table.

Default Value

None.

Remarks

A common value for this property is C:\Winnt\Profiles\[LogonUser]\NetHood\.


LIMITUI Property

If this property is set, the UI level used when installing this package is capped as Basic. This property can be used when a package has no authored UI to use the Installer's built in default UI.

Set By

Property table or command line.

Used By

Installer uses this value to determine which UI to display.

Default Value

None.

Remarks

On Windows NT 5.0, the LIMITUI property will not prevent an uninstall. If the LIMITUI property is set, a user can uninstall an application by the following methods:

  • msiexec /x <path to MSI or ProductCode>
  • right-clicking on the MSI file, then clicking Uninstall
  • Calling the MsiInstallProduct API


OutOfDiskSpace Property

This property is set to a value of TRUE by the installer if any volume that is a target of the current install has insufficient disk space to accommodate the proposed installation. If all volumes have sufficient space, the value is FALSE.

Set By

This property is valid at any time after the CostInitialize action has been executed. The OutOfDiskSpace property status is dynamically updated any time the total install cost is re-calculated (for example, any time the install state of any feature is changed via the Selection dialog).

Used By

Selection resolution actions use this value to cancel an installation and generate a dialog box.


PATCH Property

This property is the full path of the current patch package. Setting this property causes the installer to apply the patch.

Set By

The PATCH property is set by the command line or with MsiApplyPatch. The PATCH property is set only during the first application of the patch. The patch will continue to be applied for each subsequent configuration of the product, but the PATCH property will not be set.

Used By

Remarks

The PATCH property can be used in conditional expressions to control an action or user interface that is performed only during the first application of the patch.

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


PersonalFolder Property

Full path to the Personal folder for the current user.

Set By

Installer at initialization.

Used By

Actions and Directory table.

Default Value

None.

Remarks

Common values for this property are C:\Winnt\Profiles\[LogonUser]\Personal\ (Windows NT) and C:\My Documents\ (Windows 95 and Windows 98).


PhysicalMemory Property

The PhysicalMemory property gives the size of the installed RAM in Megabytes.

Set By

This property is set by the installer at initialization.

Used By

Actions and condition expressions.

Default Value

None.


PIDTemplate Property

This property contains the string used as a template for the PIDKEY property. For the syntax used in the template, see the MaskedEdit control type.

Set By

The value is initially set in the Property Table.

Used By

ValidateProductID Action uses this value to validate the Product ID.

Default Value

None.


Preselected Property

The Preselected Property indicates that features have already been selected and that the selection dialog need not be shown.

Set By

This property is set by the Installer during the resumption of a suspended install or when properties such as ADDLOCAL or REMOVE are used to select features at the command line.

Used By

Conditional expressions which depend on whether or not 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.

Default Value

None.


PrintHoodFolder Property

Full path to the PrintHood (Printer Neighborhood) folder for the current user. Not set for Win9x.

Set By

Installer at initialization.

Used By

Actions and Directory table.

Default Value

None.

Remarks

A common value for this property is C:\Winnt\Profiles\[LogonUser]\PrintHood\.


ProductCode Property

A unique identifier for the particular product release, represented as a string GUID, e.g. "{12345678-1234-1234-1234-123456789012}". This ID must differ for different versions and languages.

Set By

Authored into Property table. REQUIRED.

Used By

Advertised as a product property, as the primary method of specifying the product.

Default Value

None.


ProductID Property

The ProductID property is set to the full Product ID after a successful validation.

Set By

Following a successful validation, this property is set by the ValidateProductID action or the ValidateProductID ControlEvent.

Used By

This value is displayed by the UI and used by the RegisterProduct action.

Default Value

None.


PIDKEY Property

This property contains the part of the Product ID entered by the user.

Set By

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.

Used By

The ValidateProductID action validates the Product ID entered by the user by comparing the PIDKEY property to the PIDTemplate property.

Default Value

None.


PRODUCTLANGUAGE Property

The numeric language ID.

Set By

Set on the command line.

Used By

Advertised as a product property, this value is used to apply the correct language transform in the case of a multi-language product. .

Default Value

0.

Remarks

The PRODUCTLANGUAGE property is applied only during the installation or advertisement of a product. Since the installer must use the same language for later maintenance of the product, the PRODUCTLANGUAGE property cannot be set in maintenance mode.


ProductName Property

The ProductName property contains the human-readable name of the application being installed (e.g. Microsoft Office 97). This is only used for display purposes.

Set By

Authored into Property table. REQUIRED. May be changed by transform.

Used By

Advertised as a product property and used for display purposes.

Default Value

None.

Remarks

None.


ProductVersion Property

The string format of the product version, as a numeric value.

Set By

Authored into Property table. REQUIRED.

Used By

Advertised as a product property.

Default Value

None.

Remarks

Only the major and minor versions are used for the advertised property.


ProgramFilesFolder Property

Full path to the Program Files folder.

Set By

Installer at initialization.

Used By

Actions and Directory table.

Default Value

None.

Remarks

A common value for this property is C:\Program Files\.


ProgramMenuFolder Property

Full path to the Program 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, than this property is set to the folder in the "All Users" profile.

Set By

Installer at initialization.

Used By

Actions and Directory table.

Default Value

None.

Remarks

Common values for this property are C:\Winnt\Profiles\[LogonUser]\Start Menu\Programs\ (Windows NT) and C:\Windows\Start Menu\Programs\ (Windows 95 and Windows 98).


REBOOT Property

If this property is set to "Force" the installation will reboot at the end, regardless of what the actions require.If the property is set to "Suppress" the installation will not reboot in case of reboots that happen at the end of the installation before the new program can be used. If the reboot is needed to continue the installation, the reboot will still take place.

Set By

Command line.

Used By

MsiEngine uses this value at termination to override the reboot decision made by the actions.

Default Value

None.

Remarks

This property is typically used by an administrator who installs several products at the same time and wants to have only one reboot at the end of the series of installations.


RecentFolder Property

Full path to the Recent folder for the current user. Not set for Win9x.

Set By

Used By

Actions and Directory table.

Default Value

None.

Remarks

A common value for this property is C:\Winnt\Profiles\[LogonUser]\Recent\.


REINSTALL Property

The property value denotes a list of features, delimited by commas, that are to be reinstalled. The features listed are to be found in the Feature column of the Feature table. Optionally, the value could be All to denote reinstalling all features. Thus, if you wish to reinstall all features you would provide the command line REINSTALL=All to the installer.

Set By

Command line.

Used By

MsiEngine uses this value to determine which features are to be reinstalled.

Default Value

None.

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 will be reinstalled, IF the currently installed file is a lesser version (or is not present). By default, no registry entries will be rewritten.

Note that even if REINSTALL is set to "ALL", only those features that were already installed previously will be reinstalled. Thus, if REINSTALL is set for a product that is yet to be installed, no installation action will take place at all.


REINSTALLMODE Property

A string containing letters that specify 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.

Set By

Command line.

Used By

MsiEngine uses this value to determine the type of reinstall (if any) to perform.

Default Value

By default the REINSTALLMODE is "romus".

Reinstall Option Codes

r | (iefInstallEnable) | Enable reinstall of any files/registry found to be invalid.
p | (iefOverwriteNone) | Reinstall only if file is missing (i.e. verify that the file is present).
o | (iefOverwriteOlderVersions) | Reinstall if file is missing, or an older version is present.
e | (iefOverwriteEqualVersions) | Reinstall if file is missing, or an equal or older version is present
d | (iefOverwriteDifferingVersions) | Reinstall if file is missing, or a different version is present
c | (iefOverwriteCorruptedFiles) | Reinstall if file is missing, or corrupt (i.e. the stored checksum doesn't match the computed value).
a | (iefOverwriteAllFiles) | Force all files to be reinstalled, regardless of checksum or version
u | (iefInstallUserData) | Re-write all required user registry entries.
m | (iefInstallMachineData) | Re-write all required local machine registry entries.
s | (iefInstallShortcuts) | Reinstall all shortcuts, overwriting any existing shortcut.

All of the reinstall options shown above, except for iefInstallEnable, can actually be thought of as "detection" flags, which are used to detect that the feature or features specified by the REINSTALL property are installed properly. If any of the specified detection operations fail during the reinstall, this fact will be logged for informational purposes. However, the invalid installation will actually be repaired only if the iefInstallEnable option is also set. For example, if the iefOverwriteCorruptedFiles flag is set, corrupted files will be detected and logged on reinstall, but the corrupted files will actually be repaired (by reinstallation) only if the iefInstallEnable flag is also specified.

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 will actually be "reinstalled". Thus, in this case, REINSTALLMODE actually specifies the "overwrite" mode for a normal install.

Note Only those files that are designated in the File table as containing checksum information will ever be verified for accurate checksum.


REMOVE Property

The property value denotes a list of features, delimited by commas, that are to be removed, if installed. The features listed are to be found in the Feature column of the Feature table. Optionally, the value could be All to denote removing all features. Thus, if you wish to remove all features (i.e. uninstall the entire product), you would provide the command line REMOVE=All to the installer.

Set By

Command line.

Used By

MsiEngine uses this value to determine which features are to be removed.

Default Value

None.

Remarks

Note that the feature names are case-sensitive.


Resume Property

Set when resuming a suspended install. This property can be used to determine what text to show the user 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?".

Set By

Installer at initialization.

Used By

UI conditionalization uses this value to determine which install dialog to display.

Default Value

None.


ROOTDRIVE Property

Set to the default drive for the install. This property supplies the default paths for any undefined root directories in the Directory table. When in ADMIN mode, this is set to the first writable connected network drive found. When no network drives are found or when not in ADMIN mode, the location of the writable local drive with the most available free disk space is used.

The value for this property must end with '\'.

Set By

Command line.

Used By

Directory Table use this value to determine the drive used for an application installation.

Default Value

None.


ScreenX Property

Width, in pixels, of the screen.

Set By

Installer at initialization.

Used By

Actions and condition expressions use this value to establish screen width.

Default Value

None.

Remarks

None.


ScreenY Property

Height, in pixels, of the screen.

Set By

Installer at initialization.

Used By

Actions and condition expressions use this value to establish screen height.

Default Value

None.


SCRIPTFILE Property

If this property is set, a script file is created containing all operations executed during the install. This property defines the location of the script file. If a relative path is given, the path is assumed to be relative to the location of the installation package.

Set By

Command line.

Used By

MsiEngine uses this value to determine if and where to create a script file.

Default Value

None.

Remarks

This property is completely unrelated to the EXECUTEMODE property. In other words, if this property is set, the script will be created regardless of the installer's execution mode.


SendToFolder Property

Full path to the SendTo folder for the current user.

Set By

Installer at initialization.

Used By

Actions and Directory table.

Default Value

None.

Remarks

Common values for this property are C:\Winnt\Profiles\[LogonUser]\SendTo\ (Windows NT) and C:\Windows\SendTo\ (Windows 95 and Windows 98).


ServicePackLevel Property

The numerical value of the operating system service pack, if one is installed.

Set By

Installer at initialization

Used By

Conditional expressions.

Default Value

None.


SharedWindows Property

Set when the system is operating as Shared Windows.

Set By

Installer at initialization.

Used By

Actions and conditional expressions.

Default Value

None.


SHORTFILENAMES Property

Setting the SHORTFILENAMES property causes short file names to be used rather than long file names. This property may be set during an ADMIN install to create a source image having only short file names.

Set By

This property can be set by the user at the command line to disable long file names.

Used By

Actions use this property for directory resolution.

Default Value

Long names will be used by the installer if the SHORTFILENAMES property is not set and the target volume supports long names. Short names will be used by the installer if the target volume does not support long names.

Remarks

When the SHORTFILENAMES property is set, the installer will create folders and install files using short file names from any short|long pairs listed in the File table or Directory table.


SOURCEDIR Property

Root directory containing the source files (either the source cabinet file, or the source file tree).

Set By

Command line.

Used By

This value is used for directory resolution.

Default Value

The directory containing the installation package.


SOURCELIST Property

The SOURCELIST property is a semicolon delimited list of network or URL source paths that are added to each user's source list for that product.

Set By

The SOURCELIST property can be set at the command line or in the Property table.

Used By

During the installation of a feature or product, the installer searches the source list for a valid path to the installation package. The author of an installation package uses the SOURCELIST property to extend the list of potential source paths that are searched.

Default Value

During every installation the installer will check to see if the property is set. If the SOURCELIST property is not set, then the installer will use the existing source list.

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.


StartMenuFolder Property

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, than this property is set to the folder in the "All Users" profile.

Set By

Installer at initialization.

Used By

Actions and Directory table.

Default Value

None.

Remarks

Common values for this property are C:\Winnt\Profiles\[LogonUser]\Start Menu\ (Windows NT) and C:\Windows\Start Menu\ (Windows 95 and Windows 98).


StartupFolder Property

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.

Set By

Installer at initialization.

Used By

Actions and Directory table.

Default Value

None.

Remarks

Common values for this property are C:\Winnt\Profiles\[LogonUser]\Start Menu\Programs\Startup\ (Windows NT) and C:\Windows\Start Menu\Programs\Startup\ (Windows 95 and Windows 98).


SupportPhone Property

Technical support phone number(s).

Set By

Authored into Property table. Optional.

Used By

Product maintenance applets display this value.

Default Value

None.


SupportURL Property

Internet address for technical support.

Set By

Authored into Property table. Optional.

Used By

Product maintenance applets display this value.

Default Value

None.


System16Folder Property

Full path to folder for 16-bit system DLLs.

Set By

Installer at initialization.

Used By

Actions and Directory table.

Default Value

None.

Remarks

Common values for this property are C:\Winnt\System\ (Windows NT) and C:\Windows\System\ (Windows 95 and Windows 98).


SystemFolder Property

Full path to the System folder.

Set By

Installer at initialization.

Used By

Actions and Directory table.

Default Value

None.

Remarks

Common values for this property are: C:\Winnt\System32 (Windows NT) and C:\Windows\System\ (Windows 95 and Windows 98).

This folder is normally a subfolder of the Windows folder. However, it will reside on a server when configured for Shared Windows.


TARGETDIR Property

TARGETDIR must be the name of one root in the Directory table. It is used as the location to copy the Installer installation package during an ADMIN install.

Set By

Command line, user interface.

Used By

Actions.

Default Value

None.


TempFolder Property

Full path to the Temp folder.

Set By

Installer at initialization.

Used By

Actions and Directory table.

Default Value

None.

Remarks

A common value for this property is C:\Temp.


TemplateFolder Property

Full path to the Template folder for the current user.

Set By

Installer at initialization.

Used By

Actions and Directory table.

Default Value

None.

Remarks

Common values for this property are C:\Winnt\Profiles\[LogonUser]\ShellNew\ (Windows NT) and C:\Windows\ShellNew\ (Windows 95 and Windows 98).


TextHeight Property

The height (ascent + descent) of characters, given in logical units.

Set By

Installer at initialization.

Used By

Actions and condition expressions.

Default Value

None.


TRANSFORMS Property

A string containing a list of transforms to be applied to the database.

Set By

Command line.

Used By

MsiEngine uses this value to transform the database.

Default Value

Undefined.

Remarks

Transforms will be applied in the order they are listed in the string. To specify multiple transforms, separate each with a semi-colon (;).

Transforms can reside in three locations. The format for specifying the transforms varies based on its location:

Location | Format
file | filename
child storage in database | :transformname

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

Example

Suppose the following transforms need to be applied:

  • trans1, located in a file in c:\transforms
  • trans2, located in a child storage of the database

The string would be: c:\transforms\trans1;:trans2

The TRANSFORMS property is applied only during the installation or advertisement of a product. Since the installer must use the same transform for later maintenance of the product, the TRANSFORMS property can't be set in maintenance mode.


UpdateStarted Property

Set when changes to the system have begun for this install. This includes the case when a suspended install is resumed.

Set By

Installer at initialization.

Used By

UI conditionalization uses this value to select a dialog box. If this property is set, the user will be asked after an error and cancellation whether to restore or to continue later .

Default Value

None.


UpgradeCode Property

This 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.

Set By

The UpgradeCode of a product is set by the author of the upgrade package and registered in Darwin information.

Used By

Default Value

None.


USERNAME Property

User performing installation.

Set By

Set by registry properties, override on command line.

Used By

UI dialogs use this value for personalization actions.

Default Value

Default value may be put in database Property table.


UserSID Property

The UserSID Property is set to the string form of the user's security identifier (SID). This property is only set on Windows NT.

Set By

Set by installer at initialization.

Used By

This property is used by custom actions that need to access registry keys under HKEY_CURRENT_USER.

Default Value

None.

Remarks

When a custom action is executed in the installation service, it cannot access HKEY_CURRENT_USER directly. Instead, it must open a key beneath HKEY_USERS. The value of this property is the name of the key under HKEY_USERS which may be used in place of HKEY_CURRENT_USER.


Version9X Property

This property gives the version number for the Windows 95 or Windows 98 operating system.

Set By

This property is set by the installer at initialization.

Used By

Actions and condition expressions dependent upon the Windows 95 or Windows 98 operating system use this value.

Value

The value of this property is an integer: MajorVersion * 100 + MinorVersion. The property remains undefined if the operating system is not Windows 95 or Windows 98.

Remarks

Condition expressions can test for the version of Windows 95 or Windows 98 by using the property name or may verify the version by using a comparison operator.


VersionNT Property

The version number for the Windows NT operating system, undefined if the operating system is not Windows NT. The value is an integer: MajorVersion * 100 + MinorVersion.

Set By

Installer at initialization.

Used By

Windows NT operating system dependent actions and condition expressions use this value.

Remarks

Condition expressions may test for Windows NT simply by using the property name, or may verify the version using a comparison operator.


VirtualMemory Property

Amount of available page file space in Megabytes.

Set By

Installer at initialization.

Used By

Actions and condition expressions.

Default Value

None.


WindowsBuild Property

The build number of the operating system.

Set By

Installer at initialization.

Used By

Actions and conditional expressions.

Default Value

None.


WindowsFolder Property

Full path to the Windows folder.

Set By

Installer at initialization.

Used By

Actions and Directory table.

Default Value

None.

Remarks

Common values for this property are C:\Winnt (Windows NT) and C:\Windows (Windows 95 and Windows 98).

This folder will be local, even when configured for shared Windows.


WindowsVolume Property

This property is set 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, since the ROOTDRIVE Property does not necessarily equal this drive.

Set By

Installer at initialization.

Used By

Actions and directory resolution use this value.


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.

To conveniently store information in Microsoft® Windows® Explorer, you can use the summary information stream, which is accessible through the IStream interface. 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 is very convenient for storing information that can be viewed with Microsoft® Windows® Explorer. Microsoft® Windows® installer sets the summary information stream properties by default. The default value for each type of database is described in this section. The installer uses certain database and summary properties to populate the summary information stream for a database.

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.

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 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.


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 | Installer Usage
Codepage Property | PID_CODEPAGE | 1 | VT_12 | Specifies the name of the code page. This property is static.
Title | PID_TITLE | 2 | VT_LPSTR | Specifies the database type.
Subject | PID_SUBJECT | 3 | VT_LPSTR | Specifies the product name.
Author | PID_AUTHOR | 4 | VT_LPSTR | Specifies the vendor.
Keywords | PID_KEYWORDS | 5 | VT_LPSTR | Includes Help for the user.
Comments | PID_COMMENTS | 6 | VT_LPSTR | Includes Help for the user.
Template | PID_TEMPLATE | 7 | VT_LPSTR | Specifies the platform language IDs.
Last Saved By | PID_LASTAUTHOR | 8 | VT_LPSTR | Specifies the user name of the person who last modified the database.
Revision Number | PID_REVNUMBER | 9 | VT_LPSTR | Specifies the package code for a package.
Last Printed | PID_LASTPRINTED | 11 | VT_FILETIME | Specifies the maintenance database when the installation occurred.
Create Time/Date | PID_CREATE_DTM | 12 | VT_FILETIME | Specifies the product release date.
Last Save Time/Date | PID_LASTSAVE_DTM | 13 | VT_FILETIME | Specifies the last database modification.
Page Count | PID_PAGECOUNT | 14 | VT_I4 | Specifies the minimum installer version.
MSI Source Type | PID_MSISOURCE | 15 | VT_I4 | Specifies the installation source type.
Character Count | PID_CHARCOUNT | 16 | VT_I4 | Specifies the transform restrictions.
Creating Application | PID_APPNAME | 18 | VT_LPSTR | Specifies which application created the installation database.
Security | PID_SECURITY | 19 | VT_I4 | Specifies that the status is read-only.

The installer currently maintains two storage formats: a product-specific installation database, and a language- or version-specific transform. 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 Properties for Installation Databases and Transforms

Summary properties for installation databases and transforms are described in the following table:

Summary Property | Installation Database | Transform
Title | [SummaryTitle] (for example, the installation database for the property.) | [SummaryTitle] (for example, the transform for the property.)
Subject | [ProductName Property] | [ProductName Property]
Author | Microsoft Corporation | Microsoft Corporation
Keywords | [SummaryKeywords] | [SummaryKeywords]
Comments | [SummaryComments] (For example, an installation database contains the logic and data required to install or modify the installation of a product on a user's computer.) | [SummaryComments] (For example, a transform is a set of changes to be applied to an installation database prior to processing the database. You can use transforms to create language versions, upgrades, and so on.)
Template | Platform, default language ID, other language IDs. | Base platform, base language ID.
Last Saved By | NULL | New platform, new language ID.
Revision Number | Product code and version | Package code for an installer package.
Last Printed | Installation time. | NULL
Create Time/Date | Time and date stamped at Microsoft before shipment. | Time and date stamped at Microsoft before shipment.
Last Saved Time/Date | NULL | NULL
Page Count | The installer version. | The installer version.
Source Type | Type code. | NULL
Character Count | NULL | Transform restrictions.
Creating Application | The installer | The installer
Security | 2 (read-only recommended.) | 4 (read-only enforced)


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.

Note 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.

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 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 Property
  • Last Saved By Summary Property
  • Last Saved Time Date Summary Property
  • Msi Source Type 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 is used to convey to a file browser who initially created an installer 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. The upper word contains the transform validation flags. The lower word contains the transform error condition flags.


Codepage Summary Property

The Codepage Summary property identifies the codepage used to display the Summary Information.


Comments Summary Property

The Comments Summary Property is used to convey the general purpose of the installer database. By default 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. But for localization reasons and to allow the modification of this summary property.


Create Time/Date Summary Property

The Create Time/Date Summary Property is used to convey when the installer database was created. This property is set at Microsoft as part of the authoring process and never changes.


Creating Application Summary Property

The Creating Application Summary Property is used to convey what application created the installer database. In general the value for this summary property is "Microsoft installer". However, over time corporate customers and/or OEMs may use other tools, via COM, to create installer databases.


Keywords Summary Property

This summary property is for use by file browsers to hold keywords that can permit the database file to be found in a keyword search. The set of keywords typically will include "Installer" as well as product-specific keywords, and may be localized.


Last Printed Property

The installer does not use this property, it is NULL in all databases.


Last Saved By Summary Property

In an installer database the Last Saved By Summary Property is used to keep track of who made the last changes to the database. Initially the value for this summary property is set to NULL. However, should a user choose to make modifications to an installation the value for this summary property changes. The value is set to the value of the USERNAME property defined by the installer.

Transform
In a transform this property is used for a different purpose. It contains the platform and language ID(s) that a database should have after it has been transformed. In other words, it specifies what the Template property should be set to in the new database. See the description of the Template property for information about the form of this property.


Last Saved Time/Date Summary Property

The Last Saved Time/Date Summary Property is used to convey 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.


MSI Source Type Summary Property

The MSI Source Type Summary Property is used to indicate the type of source file image. If this property is not present, it defaults to 0. The location of the image is determined by the SOURCEFILE property, which defaults to the location of the installer package. Note that this property is stored in place of the standard Count property.

  1. Tree image matching the Directory table, long file names.
  2. Tree image matching the Directory table, short file names.
  3. Cabinet and files matching the Media table, long file names.
  4. Cabinet and files matching the Media table, short file names.


Page Count Summary Property

The Page Count Summary Property contains the minimum installer version required. It is stored as an integer in the form: Major * 100 + minor.


Revision Number Summary Property

The Revision Number Summary Property contains the package code for an installer package.


Security Summary Property

The Security Summary Property is used to convey whether the file should be opened read-only or read-write. Possible values are:

  1. No restriction
  2. Read-only recommended
  3. Read-only enforced


Subject Summary Property

This summary property is used to convey 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 info property is:

[platform property][,platform property][,...];[language id][,language id][,...].

For example, the following are all valid values for the Template Summary property:

  • Alpha,Intel;1033
  • Intel,Alpha;1033
  • Alpha;1033
  • Intel;1033
  • ;1033
  • ;
  • Alpha;1033,2046
  • Intel ;1033,2046
  • Intel;0

If the current platform doesn't 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.

Specifying a language ID of 0 indicates that a 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 will be done. 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 are used to 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.


Title Summary Property

The Title Summary Property is used to convey what the *.msi file is, so the value for this summary property is either "Installation Database" or "Transform", and it never changes.


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 general information on the installer, see About Windows Installer.


About the Automation Interface

To be written


Using the Automation Interface

To be written


Access to C++ Libraries

An MsiInstall object must be created initially to load the automation support that is 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. When possible, a pair of Get and Set C++ methods are exposed to Visual Basic as a single property. Where appropriate, 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.


Creating the MsiInstall Object

For OLE to access the automation, the DLL must be self-registered. The OLE ProgID used to create the MsiInstall object is Msi.ApiAutomation. If the DEBUG build automation is registered, the ProgID Msi.ApiAutoDebug is registered as well. If the SHIP build is registered last, both may be used.


Automation Interface Reference

This section contains reference material for the Microsoft® Windows® installer objects.

  • MsiDatabase Object
  • MsiEngine Object
  • MsiInstall Object
  • MsiRecord Object
  • MsiSummaryInfo Object
  • MsiUIPreview Object
  • MsiView Object


MsiDatabase Object

The MsiDatabase object accesses an installer database.

Before the MsiDatabase object is released (by going out of scope or by setting the object variable to Nothing), the Commit method must be called to write out all persistent changes, else an implicit rollback is performed at object destruction.

Query API Sequencing

The normal course of data access is summarized below:

  1. The client obtains a database object (MsiInstall.OpenDatabase).
  2. Database.OpenView is called, specifying a SQL query.
  3. View.Execute is called, supplying any parameters in an MsiRecord object.
  4. View.Fetch is called repeatedly and returns MsiRecord objects until exhausted.
  5. View.Modify may be called to update a fetched record.
  6. View.Close is called, which releases the query and unfetched records.
  7. Database.Commit is called to persist any database updates.

Properties

DatabaseState

SummaryInformation

TablePersistent

Methods

ApplyTransform

Commit

CreateTransformSummaryInfo

EnableUIPreview

Export

GenerateTransform

Import

Merge

OpenView

PrimaryKeys


DatabaseState Property

This is the DatabaseState property of the MsiDatabase object. This property returns the persistence state of the database as one of enum idsEnum:

idsRead | = 0 | Database opens read-only; changes are not saved.
IdsWrite | = 1 | Database is fully operational for read and write.

Syntax

object.DatabaseState

Parts

object
MsiDatabase object.


SummaryInformation Property (MsiDatabase Object)

This is the SummaryInformation property of the MsiDatabase object. This property returns an MsiSummaryInfo object that can be used to examine, update, and add properties to the SummaryInformation stream.

Syntax

object.SummaryInformation(maxProperties)

Parts

object
MsiDatabase object.
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 read-only.


TablePersistent Property

This is the TablePersistent property of the MsiDatabase object. This property returns the persistence state of the table as one of enum iecEnum:

iecFalse | = 0 | Table is temporary.
IecTrue | = 1 | Table is persistent.
IecNone | = 2 | Table is not present in the database.
IecError | = 3 | Invalid or missing table name.

Syntax

object.TablePersistent table

Parts

object
MsiDatabase object.
table
Required name of the table.


ApplyTransform Method

This is the ApplyTransform method of the MsiDatabase object. This method applies the given transform to this database.

Syntax

object.ApplyTransform storage, errorConditions

Parts

object
MsiDatabase object.
storage
Required MsiDatabase object containing the transform.
errorConditions
The error conditions that should be suppressed, specified as an integer combination of the values below.
iteAddExistingRow | Adding a row that already exists.
iteDelNonExistingRow | Deleting a row that doesn't exist.
iteAddExistingTable | Adding a table that already exists.
iteDelNonExistingTable | Deleting a table that doesn't exist.
iteUpdNonExistingRow | Updating a row that doesn't exist.

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 then. 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.


Commit Method

This is the Commit method of the MsiDatabase object. This method finalizes the persistent form of the database. All persistent data is written to the writeable database. No temporary columns or rows are written. This method has no effect on a database opened 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
MsiDatabase object.


CreateTransformSummaryInfo Method

This is the CreateTransformSummaryInfo method of the MsiDatabase object. This method 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 properties.

Syntax

object.CreateTransformSummaryInfo reference, storage, long errorConditions, long validation

Parts

object
Database that includes the changes.
reference
Required database that does not include the changes.
storage
Required MsiDatabase object where the transform is to be stored.
errorConditions
Required error conditions that should be suppressed when the transform is applied. Choose either iteNone — none of the following conditions — or combine one or more of the following:
iteAddExistingRow | Adding a row that already exists.
IteDelNonExistingRow | Deleting a row that doesn't exist.
IteAddExistingTable | Adding a table that already exists.
IteDelNonExistingTable | Deleting a table that doesn't exist.
IteUpdNonExistingRow | Updating a row that doesn't exist

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.

Choose either itvNone — validate no properties — or combine one or more of the following:
itvLanguage | Default language must match base database.
ItvProduct | Product must match base database.
ItvPlatform | Platform 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.
itvMajVer | Check major version only.
ItvMinVer | Check major and minor version only.
ItvUpdVer | 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.
itvLess | Applied db version | < base db version
itvLessOrEqual | Applied db version | <= base db version
itvEqual | Applied db version | = base db version
itvGreaterOrEqual | Applied db version | >= base db version
itvGreater | Applied db version | > base db version


EnableUIPreview Method

This is the EnableUIPreview method of the MsiDatabase object. This method 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
MsiDatabase object.


Export Method

This is the Export method of the MsiDatabase object. This method copies the structure and data from a specified table to a text archive file.

Syntax

object.Export table, path, file

Parts

object
MsiDatabase object.
table
Required name of the database table; case-sensitive if using the MSI database.
path
Required MsiPath object set 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

This is the GenerateTransform method of the MsiDatabase object. A transform is a way of recording changes to a database without altering the original database. The GenerateTransform method creates a transform which, when applied to the object database, results in the reference database. The transform is stored in the storage object.

Syntax

object.GenerateTransform reference, storage, long Reserved1, long Reserved2

Parts

object
Database that includes the changes.
reference
Required database that does not include the changes.
storage
Required MsiDatabase object where the transform is to be stored. This is optional.
Reserved1
Reserved argument that is not used.
Reserved2
Reserved argument that is not used.

Remarks

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, names, or column definitions of the existing columns as defined in the base table. If neither table contained data, and columns were removed from the reference table, the resulting table would be identical to the base table.

This method returns a boolean value; True if a transform was generated, False if a transform was not generated due to no differences. An error is generated if the method failed.

If storage 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.


Import Method

This is the Import method of the MsiDatabase object. This method imports a database table from a text archive file, dropping any existing table.

Syntax

object.Import(path, file)

Parts

object
MsiDatabase 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

This is the Merge method of the MsiDatabase object. This method merges the reference database with the base database.

Syntax

object.Merge reference, errorTable

Parts

object
MsiDatabase object.
reference
Required MsiDatabase 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

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 since the operation to update the Error table fails if a column is not nullable. A newly created table can be passed in as well since 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)

OpenView Method

This is the OpenView method of the MsiDatabase object. This method returns an MsiView object representing the query specified by a SQL string.

Syntax

object.OpenView(sql)

Parts

object
MsiDatabase object.
sql
Required SQL query string.

Remarks

For information about SQL syntax implemented in the installer, see SQL Syntax.


PrimaryKeys Method

This is the PrimaryKeys method of the MsiDatabase object. This method returns an MsiRecord 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
MsiDatabase object.
table
Required name of an existing table. An error is generated if the table does not exist.

Remarks

The PrimaryKeys method cannot be used with the _Tables table or the _Columns table.


MsiEngine Object

The MsiEngine object controls the installation process. It opens the install database, which contains the installation tables and data. The MsiEngine 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.

Properties

Application

ComponentCurrentState

ComponentRequestState

Database

FeatureCost

FeatureCurrentState

FeatureRequestState

FeatureValidStates

Language

Mode

Property

SourcePath

TargetPath

VerifyDiskSpace

Methods

DoAction

EvaluateCondition

FormatRecord

Message

Sequence

SetInstallLevel


Application Property

Syntax

object.Application

Parts

object
MsiEngine object.

Remarks

For a list of common properties, see Property Summary.


ComponentCurrentState Property

This is the ComponentCurrentState property of the MsiEngine object. This read-only property returns the current installed state of the designated component. See the ComponentRequestState property for state values.

Syntax

object.ComponentCurrentState(component)

Parts

object
MsiEngine object.
component
Required string name of the requested component, primary key into the Component table.


ComponentRequestState Property

This is the ComponentRequestState property of the MsiEngine object. This property is used to obtain or request a change in the Action state of a row in the Component table.

Syntax

object.ComponentRequestState(component)

Parts

object
MsiEngine object.
component
Required string name of the component item, primary key of the Component table.

Remarks

Selection States

Null (empty) | = | Requests that no action be taken for this item.
iisAbsent | = 2: | Item is to be removed.
iisLocal | = 3: | Item is to be installed locally.
iisSource | = 4: | Item is to be installed and run from the source media.
iisDefault | = 5: | If installed, the item is to be reinstalled in the same state.


Database Property

This is the Database property of the MsiEngine object. This read-only property returns the database for the current install session as an MsiDatabase object.

Syntax

object.Database

Parts

object
MsiEngine object.


FeatureCost Property

This is the FeatureCost property of the MsiEngine object. This property returns the total amount of disk space (in units of 512 bytes) required by the specified feature and that of all the feature's 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
MsiEngine 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:
ictSelfOnly | = 0
ictChildren | = 1
ictParents | = 2
ictProduct | = 3 (not supported at this time)

state
Required element that specifies the action state to use when determining the feature cost. For example, if Local is specified, FeatureCost returns the disk space required if the specified feature and all its parent features were to be installed locally.
iisAbsent | = 2
iisLocal | = 3
iisSource | = 4


FeatureCurrentState Property

This is the FeatureCurrentState property of the MsiEngine object. This read-only property returns the current installed state of the designated feature. See the FeatureRequestState property for state values.

Syntax

object.FeatureCurrentState(feature)

Parts

object
MsiEngine object.
feature
Required string name of the requested feature, and a primary key into the Feature table.


FeatureRequestState Property

This is the FeatureRequestState property of the MsiEngine object. This property is used to obtain or request 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
MsiEngine 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 iisState parameter. For example, if iisAbsent is specified in the iisState parameter, and ALL is specified in the strFeature parameter, the entire product is removed.

Selection States

Null (empty) | = | Requests that no action be taken for this item.
iisAbsent | = 2: | Item is to be removed.
iisLocal | = 3: | Item is to be installed locally.
iisSource | = 4: | Item is to be installed and run from the source media.
iisDefault | = 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 iisLocal or iisSource, 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 iisLocal and component B set to iisSource.

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 calls for the component to be installed locally, it is installed iisLocal. If at least one feature calls for the component to be run from the source media, it is installed iisSource'. If at least one feature calls for the removal of the component, the action state is iisAbsent. See the Feature table for more information on how features are selected for installation.


FeatureValidStates Property

This is the FeatureValidStates property of the MsiEngine object. This property 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
MsiEngine 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 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 iisLocal and iisSource are valid states for the feature. If all components are set to irsLocalOnly, then iisLocal is the only valid state. If all components are set to irsSourceOnly, then iisSource is the only valid state.


Language Property (MsiEngine Object)

This is the Language property of the MsiEngine object. This read-only property represents the numeric language ID used by the current install session.

Syntax

object.Language

Parts

object
MsiEngine object.


Mode Property

This is the Mode property of the MsiEngine 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.

Syntax

object.Mode(flag)

Parts

object
MsiEngine object.
flag

Required integer value for the flag. Must be one of the following:

imfAdmin | =0 | Admin mode install, else product install.
imfAdvertise | =1 | Advertise mode of install.
imfMaintenance | =2 | Maintenance mode database loaded.
imfRollbackEnabled | =3 | Rollback is enabled.
imfLogEnabled | =4 | Log file is active.
imfOperations | =5 | Executing or spooling operations.
imfRebootAtEnd | =6 | Reboot is needed (settable).
imfRebootNow | =7 | Reboot is needed to continue installation (settable).
imfCabinet | =8 | Installing files from cabinets and files using Media table.
imfSourceShortNames | =9 | Source files use only short file names.
imfTargetShortNames | =10 | Target files are to use only short file names line.
imfWindows9x | =12 | Operating system is Windows 95 or Windows 98, but not Windows NT.
imfZawEnabled | =13 | Operating system supports advertising of products.


Property Property (MsiEngine Object)

This is the Property property of the MsiEngine object This read-write property represents the string value of a named installer property, as maintained by the MsiEngine 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
MsiEngine object.
name
Required case-sensitive name of a property, or a case-insensitive name of an environment variable prefixed by a percent sign (%).

Remarks

For a list of common properties, see Property Summary.


SourcePath Property

This is the SourcePath property of the MsiEngine object. This read-only property provides the full path to the designated folder on the source media or server image.

Syntax

object.SourcePath(folder)

Parts

object
MsiEngine object.
folder
Required case-sensitive name of a folder property as specified by a primary key of the Directory database table. An error is generated if the folder does not exist.


TargetPath Property

This is the TargetPath property of the MsiEngine object. This read-write property provides the full path to the designated folder on the installation target drive.

Syntax

object.TargetPath(folder)

Parts

object
MsiEngine object.
folder
Required case-sensitive name of a folder property as specified by a primary key of the Directory database table. An error is generated if the folder does not exist.


VerifyDiskSpace Property

Syntax

object.VerifyDiskSpace

Parts

object
MsiEngine object.

Remarks

For a list of common properties, see Property Summary.


DoAction Method

This is the DoAction method of the MsiEngine object. This method executes the action function corresponding to the name supplied. If the name is not recognized by the engine as a built-in action or as a custom action in the CustomAction table, the name is passed to the DoAction method of the MsiHandler object, which may either invoke a function or a dialog box. 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
MsiEngine object.
action
Required string name of the action to execute. Case-sensitive.

Remarks

iesNoAction | = 0 | Action not invoked, most likely does not exist.
iesSuccess | = 1 | IDOK, completed actions successfully.
iesUserExit | = 2 | IDCANCEL, user terminated prematurely.
iesFailure | = 3 | IDABORT, unrecoverable error occurred.
iesSuspend | = 4 | IDRETRY, sequence suspended, to be resumed later.
iesFinished | = 5 | IDIGNORE, skip remaining actions, not an error.
iesWrongState | = 6 | Calling sequence error, not in initialized state.
iesBadActionData | = 7 | Invalid action table condition or missing custom action.


EvaluateCondition Method

This is the EvaluateCondition method of the MsiEngine object. This method evaluates a logical expression containing symbols and values and returns an integer of the enumeration iecEnum.

Syntax

object.EvaluateCondition(condition)

Parts

object
MsiEngine object.
condition
Required string containing the logical expression. See MsiEvaluateCondition for the expression syntax.

Remarks

iecFalse | = 0 | Expression evaluates to False.
iecTrue | = 1 | Expression evaluates to True.
iecNone | = 2 | Expression is not present; caller decides interpretation.
iecError | = 3 | Syntax error in expression; cannot be evaluated.

Feature and Component State Values

2 (iisAbsent) | Feature or component is not present.
3 (iisLocal) | Feature or component is on a local machine.
4 (iecSource | Feature or component runs from source.
(Null value) | No action to be taken on feature or component.

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.


FormatRecord Method

This is the FormatRecord method of the MsiEngine object. This method returns a formatted string from a template and record data.

Syntax

object.FormatRecord(record)

Parts

object
MsiEngine object.
record
Required MsiRecord 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.
    • If a substring of the form "[$componentkey]" is found, it is replaced by the installation directory of the component, with the value componentkey used as a key into the Component table, taking into account the Component.Action column state. If the component is selected to be installed locally, it is replaced by the target directory. If the component is selected to run from source, it is replaced by the source directory. If the component is not selected, or if the component is missing, it is replaced by a Null string.
    • 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.


Message Method

This is the Message method of the MsiEngine object. This method 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
MsiEngine object.
kind
Required message type; one of imtEnum.
record
Required MsiRecord object containing a message-specific field.

Remarks

Processing by Message Types

imtOutOfMemory | Logged if 'm' in LOGMODE; passed to handler.
imtError | Logged if 'e' in LOGMODE; passed to handler.
imtWarning | Logged if 'w' in LOGMODE; passed to handler.
imtUser | Logged if 'u' in LOGMODE; passed to handler.
imtInfo | Logged if 'i' in LOGMODE; not passed to handler.
imtDiagnostic | Logged if 'd' in LOGMODE; not passed to handler if log enabled.
imtCommonData | Logged if 'c' in LOGMODE; passed to handler to cache.
imtActionStart | Logged if 'a' in LOGMODE; passed to handler for progress display.
imtActionData | Logged if 'r' in LOGMODE; passed to handler for progress display.
imtProgress | Never logged; passed to handler progress gauge.
imtActionDone | Never logged; passed to handler to remove progress dialog box.

Message Record Fields

Return Values


Sequence Method

This is the Sequence method of the MsiEngine object. This method 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 iesEnum, as described in the DoAction method.

Syntax

object.Sequence(table)

Parts

object
MsiEngine object.
table
Required string name of the table to use for sequencing.

Remarks

This method is normally called internally by top-level actions.


SetInstallLevel Method

This is the SetInstallLevel method of the MsiEngine object. This method 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
MsiEngine 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.


MsiInstall Object

An MsiInstall object must be initially created to load the automation support that is required to access the installer API functions through OLE automation. This object provides wrappers to create the top-level objects and access their methods.

Properties

Environment

FileAttributes

SummaryInformation

UILevel

Version

Methods

EnableLog

CreateRecord

FileSize

FileVersion

InstallProduct

LastErrorRecord

OpenDatabase

OpenPackage

OpenProduct

RegistryValue


Environment Property

This is the Environment property of the MsiInstall object. This read-write property is the string value for an environment variable or the current process.

Syntax

object.Environment(variable)

Parts

object
MsiInstall object.
variable
The name of the environment variable to be read or written. This is case-insensitive.


FileAttributes Property

This is the Fileattributes property of the MsiInstall object. It returns a number representing the combined file attributes for the designated path to a file or folder.

Syntax

object.FileAttributes(filePath)

Parts

object
MsiInstall object.
filePath
The required path to the file or folder. A partial path assumes the current directory (which may be set by the Installer).

Remarks

Returns -1 if the file or folder does not exist is not accessible.


SummaryInformation Property (MsiInstall Object)

This is the SummaryInformation property of the MsiInstall object. This property returns an MsiSummaryInfo object that can be used to examine, update, and add properties to the SummaryInformation stream of a package or transform.

Syntax

object.SummaryInformation(packagePath, maxProperties)

Parts

object
MsiInstall 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.


UILevel Property

This is the UILevel property of the MsiInstall object. This read-write property indicates the type of UI to be used when opening and processing subsequent packages within the current process space.

Syntax

object.UILevel

Parts

object
MsiInstall object.

Remarks

UI levels

INSTALLUILEVEL_NOCHANGE | = 0 | UI level is unchanged.
INSTALLUILEVEL_DEFAULT | = 1 | Default UI level is used.
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.


Version Property

This is the Version property of the MsiInstall object. This read-only property is the string representation of the installer version in the form "major.minor.0.build."

Syntax

object.Version

Parts

object
MsiInstall object.


CreateRecord Method

This is the CreateRecord method of the MsiInstall object. This method returns a new MsiRecord object with the requested number of fields.

Syntax

object.CreateRecord(count)

Parts

object
MsiInstall object.
count
Required number of fields, which may be 0. The upper limit is memory limited.

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

This is the EnableLog method of the MsiInstall object. This method enables logging of the selected message type for all subsequent install sessions in the current process space.

Syntax

object.EnableLog logMode, logFile

Parts

object
MsiInstall 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

i | (imtInfo) | Information-only messages
w | (imtWarning) | Warning messages; not fatal
e | (imtError) | Error messages; may be fatal
f | (imtFilesInUse) | List of files in use that need to be replaced
a | (imtActionStart) | Start of action notification
r | (imtActionData) | Action data record; contents action-specific
u | (imtUser) | User request messages
c | (imtCommonData) | UI initialization parameters
m | (imtOutOfMemory) | Out-of-memory message
p |  | Dump property table; "property = value" at engine termination
+ |  | Append if log file exists; overwrite if it exists


FileSize Method

This is the FileSize method of the MsiInstall object. This method uses the Win32 API calls to return the size of the file specified in szPath.

Syntax

object.FileSize(szPath)

Parts

object
MsiInstall object.
szPath
Required string containing the path to the file.


FileVersion Method

This is the FileVersion method of the MsiInstall object. This method uses the Win32 API calls to return the version of the path specified in szPath as a string in "#.#.#.#" format.

Syntax

object.FileVersion(szPath)

Parts

object
MsiInstall object.
szPath
Required string containing the path to the file.


InstallProduct Method

This is the InstallProduct method of the MsiInstall object. This method opens an installer package and initializes an install session.

Syntax

object.InstallProduct packagePath, propertyValues

Parts

object
MsiInstall object.
packagePath
Required string containing the path to the install package (which encompasses a database).
propertyValues
Optional string containing property=value pairs separated by white space.


LastErrorRecord Method

This is the LastErrorRecord method of the MsiInstall object. It returns a MsiRecord object containing error parameters for the most recent error from the function that produced the error record.

Syntax

object.LastErrorRecord

Parts

object
MsiInstall object.

Remarks

Only designated functions will generate an error record. The record object will be reset after the execution of this function of any function that generates an error record.


OpenDatabase Method

This is the OpenDatabase method of the MsiInstall object. This method opens an existing database or creates a new one, returning an MsiDatabase object. It generates an error if the database object cannot be successfully created and opened.

Syntax

object.OpenDatabase(name, openMode)

Parts

object
MsiInstall 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
Required enum from the following listed or a string containing the path name of the new output database file to be written to upon commit.
idoReadOnly | = 0 | Open database read-only; no persisted changes.
idoTransact | = 1 | Open database; read-write in transaction mode.
idoDirect | = 2 | Open database direct; read-write without transaction.
idoCreate | = 3 | Create new database; read-write in transaction mode.
idoCreateDirect | = 4 | Create new database; read-write without transaction mode.

Remarks

Database Specifications

The database type is determined by examining path and file content as specified below:

An MSI package if a doc file with the correct CLSID, .msi extension is typical.

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 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.


OpenPackage Method

This is the OpenPackage method of the MsiInstall object. This method opens an installer package for use with APIs that access the product database and install engine, returning an MsiEngine object.

Syntax

object.OpenPackage packagePath

Parts

object
MsiInstall object.
packagePath
Required string containing the path name of the package.

Remarks

The OpenPackage method can accept the database handle directly in lieu of the path string for the packagePath.


OpenProduct Method

This is the OpenProduct method of the MsiInstall object. This method opens an installer package for an installed product using the product code and returns an MsiEngine object.

Syntax

object.OpenProduct productCode

Parts

object
MsiInstall object.
productCode
Required string containing the unique product code (a GUID) or an activation descriptor written by the installer.


RegistryValue Method

This is the RegistryValue method of the MsiInstall object.

Syntax

object.RegistryValue(root, key, value)

Parts

object
MsiInstall object.
root
The registry root, which is either a numeric root key or a string machine name.
key
A string containing the complete key path from the root.
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 empty | 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.


MsiRecord Object

The MsiRecord 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


DataSize Property

This is the DataSize property of the MsiRecord object. This read-only property 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
MsiRecord object.
field
Required field number of the value within the record, 1-based.


FieldCount Property

This is the FieldCount property of the MsiRecord object. This read-only property 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
MsiRecord object.


IntegerData Property

This is the IntegerData property of the MsiRecord 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, iMsiNullInteger is returned.

Syntax

object.IntegerData(field)

Parts

object
MsiRecord object.
field
Required field number of the value within the record, 1-based.

Remarks

The returned value of a non-existent field is iMsiNullInteger. Attempting to store a value in a non-existent field causes an error.


IsNull Property

This is the IsNull property of the MsiRecord object. This read-only property returns True if the indicated field is Null and False if the field contains data.

Syntax

object.IsNull(field)

Parts

object
MsiRecord object.
field
Required field number of the value within the record, 1-based.


StringData Property

This is the StringData property of the MsiRecord object. This read-write property 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
MsiRecord 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. An Empty variant value sets the record field to the Null state. Attempting to store a value in a non-existent field causes an error.


ClearData Method

This is the ClearData method of the MsiRecord object. This method clears the data in all fields, setting them to Null. Any objects stored in the fields are released.

Syntax

object.ClearData

Parts

object
MsiRecord object.


FormatText Method

This is the FormatText method of the MsiRecord object. This method formats fields according to the template in field 0.

Syntax

object.FormatText

Parts

object
MsiRecord object.


ReadStream Method

This is the ReadStream method of the MsiRecord object. This method reads a specified number of bytes from a record field holding stream data.

Syntax

object.ReadStream(field, length, format)

Parts

object
MsiRecord 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:
isfInteger | = 0 | As a long integer, length must be 1 to 4.
isfBytes | = 1 | Raw data as a BSTR; one byte per character.
isfAnsi | = 2 | ANSI bytes translated to a Unicode BSTR.
isfDirect | = 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

This is the SetStream method of the MsiRecord object. This method copies the content of the specified file into the designated record field as stream data.

Syntax

object.SetStream(field, filePath)

Parts

object
MsiRecord 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.


MsiSummaryInfo Object

The MsiSummaryInfo object is used to read, create, and update document properties from the SummaryInformation stream of a storage object.

Properties

Property

PropertyCount

Methods

Persist


Property Property (MsiSummaryInfo Object)

This is the Property property of the MsiSummaryInfo object. This property sets or gets the value for the specified property in the summary information stream. The properties are read when the MsiSummaryInfo 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
MsiSummaryInfo object.
pid
Required property ID of one of the summary properties.

Remarks

Standard Summary Property IDs

(not an enumeration)

PID_DICTIONARY | 0 | Special format, not support by MsiSummaryInfo 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)

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 MsiSummaryInfo object


PropertyCount Property

This is the PropertyCount property of the MsiSummaryInfo object. This read-only property 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
MsiSummaryInfo object.


Persist Method

This is the Persist method of the MsiSummaryInfo object. This method 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
MsiSummaryInfo object.


MsiUIPreview Object

The MsiUIPreview object is used to view UI dialog boxes and billboards during authoring. This object is created by the EnableUIPreview method of the MsiDatabase object.

Properties

Property

Methods

ViewBillboard

ViewDialog


Property Property (MsiUIPreview Object)

This is the Property property of the MsiUIPreview object. This read-write property 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
MsiUIPreview 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

This is the ViewBillboard method of the MsiUIPreview object. This method displays an authored billboard using the host control in the currently displayed dialog box.

Syntax

object.ViewBillboard control, billboard

Parts

object
MsiUIPreview 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

This is the ViewDialog method of the MsiUIPreview object. This method displays an authored UI dialog box stored in the current database.

Syntax

object.ViewDialog dialog

Parts

object
MsiUIPreview object.
dialog
Required name of the dialog box, case-sensitive, and the primary key of the Dialog database table.


MsiView Object

The MsiView object represents a result set obtained when processing a query using the OpenView method of the MsiDatabase 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


ColumnInfo Property

This is the ColumnInfo property of the MsiView object. This property returns an MsiRecord 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
MsiView object.
info
Required information needed for each column:
iciNames | = 0 | Return names of all non-constant columns in result set.
iciTypes | = 1 | Return definitions of all columns in result set.

Remarks

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.

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)


Close Method

This is the Close method of the MsiView object. This method terminates query execution and releases database resources.

Syntax

object.Close

Parts

object
MsiView object.

Remarks

This method must be called before the Execute method is called again on the MsiView object unless all rows of the result set have been obtained with the Fetch method. It is called internally when the view is destroyed.


Execute Method

This is the Execute method of the MsiView object. This method accepts replaceable query parameters and executes the database query, producing a result set that can be fetched or updated.

Syntax

object.Execute record

Parts

object
MsiView object.
record
Optional MsiRecord objects containing values to replace parameter markers (?) in the SQL query.

Remarks

This method must be called before any calls to the Fetch method. If the SQL query specifies values in the predicate expression with parameter markers (?), a record must be supplied containing all of the replacement values in the exact order and of compatible data types.


Fetch Method

This is the Fetch method of the MsiView object. This method returns an MsiRecord object containing the requested column data if more rows are available in the result set, else returns an object of value Nothing.

Syntax

object.Fetch

Parts

object
MsiView 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

This is the GetError method of the MsiView object. This method 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. See msiquery.h for error enums.

Syntax

object.GetError

Parts

object
MsiView object.


Modify Method

This is the Modify method of the MsiView object. This method modifies a database row with a modified MsiRecord object obtained by the Fetch method.

Syntax

object.Modify action, record

Parts

object
MsiView object.
action
Required action to be performed on the database row. This action is one of the following:
irmInsert
Inserts the information into the database table. The database must not be read-only. The operation does not require a Fetch method to have been performed before it is called. The function fails if a row with the same primary key exists in the table.
irmInsertTemporary
Temporarily inserts the information into the database table. The information is not persisted. The database can be read-only. The operation does not require a Fetch method to have been performed before it is called. The function fails if a row with the same primary key exists in the table.
irmUpdate
Updates the information already existing in the database allowing modification of non-primary keys only. The database must not be opened read-only. The operation requires a Fetch method to have been performed before it is called and has to be called with the same record as that returned by the fetch. The function fails if the row has been deleted from the table.
irmDelete
Deletes the information already existing in the database. The database must not be opened read-only. The operation requires a Fetch method to have been performed before it is called and has to be called with the same record as that returned by the fetch. The function fails if the row has been deleted from the table.
irmRefresh
Refreshes the information in the record from the database. The database can be opened read-only. The operation requires a Fetch method to have been performed before it is called and has to be called with the same record as that returned by the fetch. The function fails if the row has been deleted from the table.
irmAssign
Inserts/updates the information in the database table. The database must not be opened read-only. The operation does not require a Fetch method to have been performed before it is called. An update operation takes place if primary keys match an existing row. An insert operation takes place if primary keys do not match any row. In either case, the current data in the record is written to a table row.
irmMerge
Inserts/validates the information in the database table. The database must not be opened read-only. The operation does not require a Fetch method to have been performed before it is called. An insert operation takes place if primary keys do not match any row. A validation operation takes place if primary keys match an existing row. The operation fails if the record data does not match the data in the table.
irmReplace
Updates/deletes-inserts the information into the database table. The database must not be opened read-only. The operation requires a Fetch method to have been performed before it is called and has to be called with the same record as that returned by the fetch. If the primary key has not been changed, an update of the table row occurs. If the primary key has been changed, the old table row is deleted and a new row corresponding to the record is inserted.
irmValidate
Validates a record, but will not validate across joins. The database can be opened read-only. The operation requires a Fetch method to have been performed before it is called and has to be called with the same record as that returned by the fetch. Validation errors can be obtained by subsequent calls to the GetError method.
irmValidateNew
Validates a record as a new record. The database must not be opened read-only. Will not validate across joins. This differs from irmValidate in that it checks for duplicate keys. The operation requires that the MsiDatabase.OpenView method be called with a modify value. Validation errors can be obtained by subsequent callings to the GetError method.
irmValidateField
Validates a field of a fetched or new record. The database can be opened read-only. Will not validate across joins. The validation depends upon the number of fields in the record. If only one field exists, it validates that field. It can also validate more fields. It should be used when the fetched/new record does not represent every column of the table. Makes repeated validate calls depending upon the number of fields in the record. Validation errors can be obtained by subsequent calls to the GetError method.
irmValidateDelete
Validates a row of a fetched record that will later be deleted. The database must not be opened read-only. Will not validate across joins. The operation requires a Fetch method. Validation errors can be obtained by subsequent calls to the GetError method. A validation error occurs if another row of a table references the primary key fields of the record to be deleted.
record
Required MsiRecord object obtained by the Fetch method with modified field data.


Glossary


A

access function
A function that accesses the installer database and the installation process. An access function is called by an installer package authoring tool to populate the installer database. See also custom installer action, installer database, and installer package authoring tool.
acquisition phase
The phase during which the exact installation procedure is determined. At the beginning of the acquisition phase, an application or a user instructs the installer to install a feature or an application. See also execution phase.
advertise
The mechanism whereby an application that is not installed is accessed as though it is installed. Only the registry entries and other necessary information are on the local computer. When a user opens the application, the installer automatically installs the necessary components. See also assign, just-in-time installation, and publish.
assign
One of the methods of advertising. An application is assigned to a user when the Start menu contains the appropriate shortcuts, icons are present, files are associated with the application, and registry entries reflect the application's installation, but the application is not actually installed. When the user tries to open an assigned application, it is installed. See also advertise, just-in-time installation, and publish.


C

component
A building-block of an application from the programmer's perspective. Examples of components are a group of related files, a COM object, or a library. See also feature.
custom installer action
An action that is not built-in to the installer. A custom installer action modifies an existing database by calling an access function. See also access function and installer package authoring tool.


E

execution phase
The installation phase during which the installer passes the information to a process with elevated privileges to generate an installation script. The process with elevated privileges then runs the script. The execution phase is only run privileged with managed applications on Windows NT. See also acquisition phase.


F

feature
A feature is a specific capability of an application as seen from the user's perspective. Separating an application into well-defined features ensures that you take advantage of the features of the installer. An example of a feature is the spelling checker in Microsoft® Word. See also component.


I

installer
The new installation technology from Microsoft. See also Microsoft Windows installer.
installer database
Contains the setup information for an application. The installer database is in the installer package.
installer function
A function you can use to enable installer functionality. These functions can be called by any application.
installer package authoring tool
Hides the complexity of the installer database by automating the creation and population of database tables. The installer package authoring tool calls access functions. See also access function, custom installer action, and installer database.


J

just-in-time installation
Keeps your application footprint small. Using this method, you can install components supporting specialized, seldom-used features only when the features are actually needed, and, in doing so, save space on most user hard disks. The feature does not have to be installed for the user interface to present it. See also advertise.


M

merge
To add information from one database to another database. See also transform.
Microsoft Windows installer
New installation technology from Microsoft. See also installer.


P

package
A file organized as COM structured storage with streams for each of the various parts of an installation, including a summary information stream. These streams contain the installer database and either a pointer to the files or the files themselves compressed into a single cabinet file. See also installer database and summary information stream.
publish
One of the methods of advertising. Publishing does not populate the user interface. However, if another application attempts to open the published application, enough information is present to assign the published application. The published application can then be used as if it is installed. A published application can also be opened through its file association or Multipurpose Internet Mail Extension (MIME) type, or a user might instigate the installation from a list of published applications. See also advertise, assign, just-in-time installation, and publish.


R

resiliency
The capability of an application to recover gracefully from errors without presenting the user with error messages.


S

source list
Contains the locations in which the installer searches for installation packages.
summary information stream
A convenient storage area for information that can be viewed with Microsoft® Windows® Explorer. The summary information stream uses COM to provide structured storage of databases. COM supports structured storage with the IStream interface. See also package.


T

transform
A transform is a set of differences between two databases. See also merge.


Appendix

The following topics contain additional information about the Microsoft® Windows® installer package:

  • Package Format
  • Command Line options


Package Format

A Microsoft® Windows® installer package is a file organized as COM structured storage. Within this package are streams for each of the various parts of an installation. These streams contain the installation database and either a pointer to the files or the files themselves compressed into a single cabinet file. The package also contains a standard summary information stream and one or more optional streams for transforms.


Command Line Options

The executable program that interprets packages and installs products is Msiexec.exe. The following table describes the command-line options for this program.

Option | Parameters | Meaning
/i | Package|ProductCode | Installs or configures a product.
/o | Property1=Value1 Property2=Value2. . . | Sets properties. This parameter is used in conjunction with /i, /f, or /n. The /o parameter can be used with /i only if you specify the package code.
/f | [ReinstallModes] Package|ProductCode | Repairs a product.
/n | Package | Installs an product on the network.
/x | Package|ProductCode | Uninstalls an product.
/a | [u|m]Package | Advertises an product. The flag 'u' advertises to the current user, while 'm' advertises to all users of the machine.
/l | [logmode]Logfile | Specifies the logfile.
/t | ProductCode | Uninstalls an product.
/q | n|b|r|f | Specifies the level of user interface to display; can be No, Basic, Reduced, or Full display.
/? or /h |  | Displays online Help.

For example, to install a product from A:\Example.msi and create a logfile using the LOGFILE property and the LOGMODE property, install the product as follows:

msiexec /i A:\Example.msi /o "LOGFILE=c:\Example.log LOGMODE=raidcupmew"

The command line for Msiexec.exe supports spaces in property values. Use single quotes (`) to delimit the values. If you want to pass a single quote in an option, escape it with a backslash (\). For example:

msiexec /p"testdb.msi" /o"SOURCEDIR=`C:\X Y\Z`"


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.