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
FieldDescription
0Template for the formatting of the resultant string. See MsiFormatRecord for more information. The fields of the record are referenced using [1] for field 1, [2] for field 2, etc.
1 through nAll subsequent fields are directly related to the fields referenced by the template in field 0.

 

If field 0 is null, the string received by the 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.

FieldDescription
0Must be null.
1Message number in the Error table.
2 through nRelated to the specified message in the Error table.

 

For example.

FieldTypeData
0stringnull
1int1304
2stringMyfile.txt

 

The resulting message received from the UI handler is:

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

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

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

INSTALLMESSAGE_COMMONDATA

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

FieldDescription
0Unused.
12 refers to the Cancel button.
2A value of 1 indicates the Cancel button should be visible.

A value of 0 indicates the Cancel button should be invisible.

 

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

FieldTypeData
0stringnull
1int2
2int0

 

INSTALLMESSAGE_ACTIONSTART

 
INSTALLMESSAGE_ACTIONDATA

The INSTALLMESSAGE_ACTIONSTART record determines the format of the ActionData record.

FieldDescription
0null
1Action name. The name in this field must be non-null.
2Action description.
3Action template. This is used for the ActionData whose message is being formatted according to this template.

 

Do not reference field 0 in the Action template message.

The INSTALLMESSAGE_ACTIONDATA record is formatted as follows.

FieldDescription
0null
1 through nDependent upon field 3 of the corresponding INSTALLMESSAGE_ACTIONSTART message or template specified in ActionText table.

 

For example, the INSTALLMESSAGE_ACTIONSTART record.

FieldTypeData
0stringnull
1stringMyAction
2stringThis is the description of "MyAction"
3stringMyAction template: field1 data is [1]. field 2 data is [2].

 

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

INSTALLMESSAGE_ACTIONDATA record.

FieldTypeData
0stringnull
1int2
2stringActionData for MyAction

 

INSTALLMESSAGE_FILESINUSE

The FILESINUSE record is a variable length record.

FieldDescription
0This field can be null. For an installation using a basic UI, this field may specify static text for display in the ListBox control of the FilesInUse dialog. For an installation using a full UI, this field has no effect because the text is specified by the authoring of the custom FilesInUse dialog box.
1Name of the file in use.
2This field identifies the process holding the file in use.

Windows Installer version 4.0:  The process id (PID) of the process, or the title of the window for the process.

Windows Installer version 3.1 and earlier:  This field must be the process id (PID) of the process.

 

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.

FieldDescription
0null
1Red.exe
2Red Window Title
3Blue.exe
4Blue Window Title

 

Note  On Windows Installer version 4.0, if the PID passed from the service does not have a window title, such as a system tray application, the file is not be displayed and the verbose log contains the following messages.
 
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.

FieldDescription
0null
1null
2Package name.
3Product code.
4Relative path if known, can be null.
50
6Whether to validate the package code. A value of '1' indicates the package code should be validated. A value of '0' indicates the package should not be validated.
7Required disk from media table. A value of '0' indicates that any disk is acceptable.

 

 

 

Show: