Export (0) Print
Expand All
Expand Minimize
2 out of 2 rated this helpful - Rate this topic

MsiProcessMessage function

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

Syntax


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.

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

Field 1 valueField 1 description
0Resets progress bar and sets the expected total number of ticks in the bar.
1Provides information related to progress messages to be sent by the current action.
2Increments the progress bar.
3Enables an action (such as CustomAction) to add ticks to the expected total number of progress of the progress bar.

 

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

Field 1 valueField 2 description
0Expected total number of ticks in the progress bar.
1Number of ticks the progress bar moves for each ActionData message that is sent by the current action. This field is ignored if Field 3 is 0.
2Number of ticks the progress bar has moved.
3Number of ticks to add to total expected progress.

 

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

Field 1 valueField 3 valueField 3 description
00Forward progress bar (left to right)
 1Backward progress bar (right to left)
10The current action will send explicit ProgressReport messages.
 1Increment the progress bar by the number of ticks specified in Field 2 each time an ActionData message is sent by the current action.
2Unused 
3Unused 

 

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

Field 1 valueField 4 valueField 4 description
00Execution is in progress. In this case, the UI could calculate and display the time remaining.
 1Creating the execution script. In this case, the UI could display a message to please wait while the installer finishes preparing the installation.
1Unused 
2Unused 
3Unused 

 

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

Version

Windows Installer 5.0 on Windows Server 2012, Windows 8, Windows Server 2008 R2 or Windows 7. Windows Installer 4.0 or Windows Installer 4.5 on Windows Server 2008 or Windows Vista. Windows Installer on Windows Server 2003 or Windows XP

Header

Msiquery.h

Library

Msi.lib

DLL

Msi.dll

See also

Installer Action Functions
Sending Messages to Windows Installer Using MsiProcessMessage

 

 

Did you find this helpful?
(1500 characters remaining)
Thank you for your feedback

Community Additions

ADD
Show:
© 2014 Microsoft. All rights reserved.