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

Syntax

C++int MsiProcessMessage(
  __in  MSIHANDLE hInstall,
  __in  INSTALLMESSAGE eMessageType,
  __in  MSIHANDLE hRecord
);

Parameters

hInstall [in]

Handle to the installation provided to a DLL custom action or obtained through MsiOpenPackage, MsiOpenPackageEx, or MsiOpenProduct.

eMessageType [in]

The eMessage parameter must be a value specifying one of the following message types. To display a message box with push buttons or icons, use OR-operators to add INSTALLMESSAGE_ERROR, INSTALLMESSAGE_WARNING, or INSTALLMESSAGE_USER to the standard message box styles used by the MessageBox and MessageBoxEx functions. For more information, see the Remarks below.

Value	Meaning
INSTALLMESSAGE_FATALEXIT	Premature termination, possibly fatal out of memory.
INSTALLMESSAGE_ERROR	Formatted error message, [1] is message number in Error table.
INSTALLMESSAGE_WARNING	Formatted warning message, [1] is message number in Error table.
INSTALLMESSAGE_USER	User request message, [1] is message number in Error table.
INSTALLMESSAGE_INFO	Informative message for log, not to be displayed.
INSTALLMESSAGE_FILESINUSE	List of files currently in use that must be closed before being replaced.
INSTALLMESSAGE_RESOLVESOURCE	Request to determine a valid source location.
INSTALLMESSAGE_RMFILESINUSE	List of files currently in use that must be closed before being replaced. Available beginning with Windows Installer version 4.0. For more information about this message see Using Restart Manager with an External UI.
INSTALLMESSAGE_OUTOFDISKSPACE	Insufficient disk space message.
INSTALLMESSAGE_ACTIONSTART	Progress: start of action, [1] action name, [2] description, [3] template for ACTIONDATA messages.
INSTALLMESSAGE_ACTIONDATA	Action data. Record fields correspond to the template of ACTIONSTART message.
INSTALLMESSAGE_PROGRESS	Progress bar information. See the description of record fields below.
INSTALLMESSAGE_COMMONDATA	To enable the Cancel button set [1] to 2 and [2] to 1. To disable the Cancel button set [1] to 2 and [2] to 0

 

hRecord [in]

Handle to a record containing message format and data.

Return Value

-1

An invalid parameter or handle was supplied.

0

No action was taken.

IDABORT

The process was stopped.

IDCANCEL

The process was canceled.

IDIGNORE

The process was ignored.

IDOK

The function succeeded.

IDNO

No.

IDRETRY

Retry.

IDYES

Yes.

Remarks

The MsiProcessMessage function performs any enabled logging operations and defers execution. You can selectively enable logging for various message types.

For INSTALLMESSAGE_FATALEXIT, INSTALLMESSAGE_ERROR, INSTALLMESSAGE_WARNING, and INSTALLMESSAGE_USER messages, if field 0 is not set field 1 must be set to the error code corresponding to the error message in the Error table. Then, the message is formatted using the template from the Error table before passing it to the user-interface handler for display.

Record Fields for Progress Bar Messages

The following describes the record fields when eMessageType is set to INSTALLMESSAGE_PROGRESS. Field 1 specifies the type of the progress message. The meaning of the other fields depend upon the value in this field. The possible values that can be set into Field 1 are as follows.

The meaning of Field 2 depends upon the value in Field 1 as follows.

The meaning of Field 3 depends upon the value in Field 1 as follows.

The meaning of Field 4 depends upon the value in Field 1 as follows.

For more information and a code sample, see Adding Custom Actions to the ProgressBar.

Display of Message Boxes

To display a message box with push buttons or icons, use OR-operators to add INSTALLMESSAGE_ERROR, INSTALLMESSAGE_WARNING, or INSTALLMESSAGE_USER with the message box options used by MessageBox and MessageBoxEx. The available push button options are MB_OK, MB_OKCANCEL, MB_ABORTRETRYIGNORE, MB_YESNOCANCEL, MB_YESNO, and MB_RETRYCANCEL. The available default button options are MB_DEFBUTTON1, MB_DEFBUTTON2, and MB_DEFBUTTON3. The available icon options are MB_ICONERROR, MB_ICONQUESTION, MB_ICONWARNING, and MB_ICONINFORMATION. If no icon options is specified, Windows Installer chooses a default icon style based upon the message type.

For example, the following call to MsiProcessMessage sends 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);

If a custom action calls MsiProcessMessage, the custom action should be capable of handling a cancellation by the user and should return ERROR_INSTALL_USEREXIT.

For more information on sending messages with MsiProcessMessage, see the Sending Messages to Windows Installer Using MsiProcessMessage.

Requirements

See Also

Installer Action Functions

Sending Messages to Windows Installer Using MsiProcessMessage

Send comments about this topic to Microsoft

Build date: 8/13/2009