Parsing Windows Installer Messages

An external UI handler can process the list of installer messages specified by the dwMessagedFilter parameter of the MsiSetExternalUI function. Some of these messages contain strings that can be used directly, and other messages may need to be parsed and processed by the external UI handler to be useful. Your external UI handler may only need to monitor Windows Installer messages without performing any operation that affects the installation.

The following Windows Installer messages contain strings that can be displayed by a dialog box and need no additional processing. These messages contain a list of buttons and icons that are to be displayed by a dialog box. You can use the MB_ICONMASK, MB_DEFMASK, and MB_TYPEMASK values to specify icons and buttons.

INSTALLMESSAGE_FATALEXIT

Premature termination of installation has occurred.

INSTALLMESSAGE_ERROR

Formatted error message.

INSTALLMESSAGE_WARNING

Formatted warning message.

INSTALLMESSAGE_INFO

Formatted log message.

INSTALLMESSAGE_USER

Formatted user message.

INSTALLMESSAGE_OUTOFDISKSPACE

Formatted message indicating an out of disk space condition

The external user handler can use the following Windows Installer messages to monitor a sequence of the Windows Installer UI. The installer sends these messages at the start of a Windows Installer UI sequence, as each dialog box is displayed, and at the end of the UI sequence. No processing is required to use these messages.

INSTALLMESSAGE_TERMINATE

This message indicates the end of the UI sequence. The string is a null string.

INSTALLMESSAGE_INITIALIZE

This message indicates that the UI sequence has started. The string is a null string.

INSTALLMESSAGE_SHOWDIALOG

The string contains the name of the current dialog box.

The following Windows Installer messages require additional processing by the external UI handler.

INSTALLMESSAGE_RESOLVESOURCE

The external user interface handler must return 0 and allow Windows Installer to handle the message. The external user interface handler can monitor for this message, but it should not perform any action that affects the installation .

INSTALLMESSAGE_FILESINUSE

The external UI should display a FilesInUse dialog in response to this message.

INSTALLMESSAGE_RMFILESINUSE

The external UI should display a MsiRMFilesInUse dialog in response to this message. Available beginning with Windows Installer version 4.0. For more information about this message see Using Restart Manager with an External UI.

INSTALLMESSAGE_ACTIONSTART

This message gives information about the current action. The format is Action [1]: [2]. [3], where a colon is used to separate Field 1 and Field 2 and a period is used to separate Field 2 and Field 3. Field [1] contains the time the action was started using the Time property format. Field [2] contains the action's name from the sequence table. Field [3] gives the action's description from the ActionText table or from the MsiProcessMessage function.

INSTALLMESSAGE_ACTIONDATA

The format of this string is specified by the Template value provided in the ActionText table or by the MsiProcessMessage function. There can be an unlimited number of INSTALLMESSAGE_ACTIONDATA messages after the INSTALLMESSAGE_ACTIONSTART message.

INSTALLMESSAGE_COMMONDATA

This message has three subtypes: Language, Caption, and CancelShow. The string can have three fields delimited by a number followed by a colon. Not all fields are required. The message can be a NULL or empty ("") string.

Language

Field 1 contains the value 0 to indicate this string contains language information. Field 2 contains a Language value that is a numeric language identifier (LANGID.) Field 3 is a value that represents an ANSI code page.

Caption

Field 1 contains the value 1 to indicate this string contains the text of a caption or title. Field 2 contains text that an external UI handler can use as a caption of title for a dialog box. Field 3 is NULL or an empty ("") string. Field 3 can be absent from the Caption message.

CancelShow

Field 1 contains the value 2 to indicate this string contains information about whether to display the cancel button. If the cancel button should be hidden, Field 2 contains the value 0. If the cancel button should be visible, Field 2 contains the value 1.

INSTALLMESSAGE_PROGRESS

This message has four subtypes: Reset, ActionInfo, ProgressReport, and ProgressAddition. The external handler should not act upon any of these messages until the first a Reset progress message is received. This provides an estimate of the total number of ticks for the progress bar.

Reset

Field 1 contains the value 0 to indicate a reset of the progress bar. Field 2 contains the total number of ticks in the progress bar. Field 3 contains the value 0 for forward progress bar motion. Field 3 contains the value 1 for backward progress bar motion. The value 0 in Field 4 means the installation is in progress and the time remaining may be calculated. The value 1 in Field 4 means script is being run and a "Please wait ..." message can be displayed. The estimate of the total number of ticks is an approximation and may be inaccurate.

ActionInfo

Field 1 contains the value 1 to indicate this string contains action information. Field 2 contains the number of ticks the progress bar moves for each ActionData message sent by the current action. If Field 3 contains the value 0, ignore Field 2. If Field 3 contains the value 1, increment the progress bar by the number of ticks in Field 2 for each ActionData message sent by the current action. Field 4 is unused.

ProgressReport

Field 1 contains the value 2 to indicate this string contains progress information. Field 2 contains the number of ticks the progress bar has moved. Field 3 is unused. Field 4 is unused.

ProgressAddition

Field 1 contains the value 3 to indicate that an action can add ticks the progress bar. Field 2 contains the number of ticks to add to total expected count of progress ticks. Field 3 is unused. Field 4 is unused.