Sending Messages to Windows Installer Using MsiProcessMessage

The messages sent using MsiProcessMessage are the same messages that are received by the INSTALLUI_HANDLER callback function if MsiSetExternalUI was called. Otherwise, Windows Installer handles the messages. For details, see Parsing Windows Installer Messages.

For example, to send an INSTALLMESSAGE_ERROR message with the MB_ICONWARNING icon and the MB_ABORTRETRYCANCEL buttons:

PMSIHANDLE hInstall;
PMSIHANDLE hRec;
MsiProcessMessage(hInstall, INSTALLMESSAGE(INSTALLMESSAGE_ERROR|MB_ABORTRETRYIGNORE|MB_ICONWARNING), hRec);

Where hInstall is the handle to the installation, provided to a custom action or the hProduct handle from MsiOpenProduct or MsiOpenPackage, and hRec is the record containing the error information to format. For information on how formatting is performed, see MsiFormatRecord.

By default, if an INSTALLMESSAGE_ERROR or INSTALLMESSAGE_FATALEXIT message is sent without specifying button type or icon types, MB_OK, no icon, and MB_DEFBUTTON1 are used.

Windows Installer does not label the ABORT button with the "Abort" string when displaying a MessageBox with the MB_ABORTRETRYIGNORE button specification, instead it labels the button with the "Cancel" string. All error messages refrain from using the word "Abort" and instead use the word "Cancel".

The hRecord parameter of the MsiProcessMessage function depends upon the message type sent to the MsiProcessMessage. The following list details the requirements of the record in relation to the message type:

INSTALLMESSAGE_FATALEXIT

INSTALLMESSAGE_INFO

INSTALLMESSAGE_OUTOFDISKSPACE

If field 0 is null, the string received by the UI handler is formatted as: 1: [data from field 1] 2: [data from field 2] meaning that for each field of the record, the string contains the field number followed by the data stored in the field.

Information messages from MsiProcessMessage are logged when MsiEnableLog, the '/l' command line option, or the logging policy specify 'I' or INSTALLLOGMODE_INFO.

INSTALLMESSAGE_ERROR

INSTALLMESSAGE_WARNING

INSTALLMESSAGE_USER

To use a message from the Error table.

For example.

The resulting message received from the UI handler is:

Error 1304. Error writing to file: Myfile.txt. Verify that you have access to that directory.

If field 0 is not null, the message from the error table is overridden. Instead, the field 0 template determines the format of the message.

The message may also specify the buttons, including the default button, and the icon for use with the message as mentioned above. The button and icon types are listed in INSTALLUI_HANDLER.

INSTALLMESSAGE_COMMONDATA

This message is sent to enable or disable the Cancel button in a progress dialog box.

For example, to disable or hide the Cancel button, the record would appear as follows.

INSTALLMESSAGE_ACTIONSTART

INSTALLMESSAGE_ACTIONDATA

The INSTALLMESSAGE_ACTIONSTART record determines the format of the ActionData record.

Do not reference field 0 in the Action template message.

The INSTALLMESSAGE_ACTIONDATA record is formatted as follows.

For example, the INSTALLMESSAGE_ACTIONSTART record.

The template for INSTALLMESSAGE_ACTIONSTART (field 3) references fields 1 and 2, the INSTALLMESSAGE_ACTIONDATA record should have 2 fields containing the warranted data. The fields could be either string or integer fields.

INSTALLMESSAGE_ACTIONDATA record.

INSTALLMESSAGE_FILESINUSE

The FILESINUSE record is a variable length record.

For example, to send a FilesInUse message showing two files in use, red.exe and blue.exe, the record has four fields plus the 0 field. The format of the record would be as shown in the following table. This example requires Windows Installer version 4.0.

Windows Installer version 3.1 and earlier: Fields 2 and 4 in the following example must contain the PIDs of the processes holding red.exe and blue.exe in use.

File In Use: -<FileName>- Window could not be found. Process ID: <PID>
No window with title could be found for FilesInUse

INSTALLMESSAGE_RESOLVESOURCE

The INSTALLMESSAGE_RESOLVESOURCE record has seven fields. For INSTALLMESSAGE_RESOLVESOURCE to work correctly, an external UI handler may not handle the INSTALLMESSAGE_RESOLVESOURCE message. Windows Installer must handle the INSTALLMESSAGE_RESOLVESOURCE message. That is, the external UI handler returns 0 to indicate "no action taken" when filtering the INSTALLMESSAGE_RESOLVESOURCE message. The best practice is to avoid sending a RESOLVESOURCE message.