Session.Message Method

Windows Installer

Session.Message Method

The Message method of the Session object performs any enabled logging operations and defers execution to the UI handler object associated with the engine. Logging may be selectively enabled for the various message types. See the EnableLog method.

If record field 0 contains a formatting string, it is used to format the data in the other fields. Else if the message is an error, warning, or user message, an attempt is made to find a message template in the Error table for the current database using the error number found in field 1 of the record for message types and return values.

Syntax

Script
Message(
  kind,
  record
)

Parameters

kind

The kind parameter is required to be one of the following values. To display a message box with push buttons and icons, calculate the value of kind by adding the standard message box styles used by MessageBox and MessageBoxEx to msiMessageTypeError, msiMessageTypeWarning, or msiMessageTypeUser. For more information see the Remarks section below.

Constant Meaning
msiMessageTypeFatalExit
&H00000000

Premature termination, possibly fatal out of memory.

msiMessageTypeError
&H01000000

Formatted error message, [1] is message number in Error table.

msiMessageTypeWarning
&H02000000

Formatted warning message, [1] is message number in Error table.

msiMessageTypeUser
&H03000000

User request message, [1] is message number in Error table.

msiMessageTypeInfo
&H04000000

Informative message for log, not to be displayed.

msiMessageTypeFilesInUse
&H05000000

List of files in use that need to be replaced.

msiMessageTypeResolveSource
&H06000000

Request to determine a valid source location.

msiMessageTypeOutOfDiskSpace
&H07000000

Insufficient disk space message.

msiMessageTypeActionStart
&H08000000

Start of action,
[1] action name,
[2] description,
[3] template for ACTIONDATA messages.

msiMessageTypeActionData
&H09000000

Action data. Record fields correspond to the template of ACTIONSTART message.

msiMessageTypeProgress
&H0A000000

Progress bar information. See the description of record fields below.

msiMessageTypeCommonData
&H0B000000

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

 

record

Required Record object containing a message-specific field.

Return Value

Constant Value
msiMessageStatusError

-1

msiMessageStatusNone

0

msiMessageStatusOk

1

msiMessageStatusCancel

2

msiMessageStatusAbort

3

msiMessageStatusRetry

4

msiMessageStatusIgnore

5

msiMessageStatusYes

6

msiMessageStatusNo

7

 

Remarks

Message Record Fields

The following describes the record field definitions when msiMessageTypeProgress is passed as the message type.

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.

Message name Value Field 1 description
MasterReset 0 Resets progress bar and sets the expected total number of ticks in the bar.
ActionInfo 1 Provides information related to progress messages to be sent by the current action.
ProgressReport 2 Increments the progress bar.
ProgressAddition 3 Enables 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 value Field 2 description
0 Expected total number of ticks in the progress bar.
1 Number of ticks the progress bar moves for each ActionData message. This field is ignored if Field 3 is 0.
2 Number of ticks the progress bar has moved.
3 Number of ticks to add to total expected progress.

 

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

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

 

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

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

 

Displaying Message Boxes

To display a message box with push buttons and icons, calculate the value of kind by adding the standard message box styles used by MessageBox and MessageBoxEx to msiMessageTypeError, msiMessageTypeWarning, or msiTypeUser. The available push button options for VBScript are vbOKOnly (MB_OK), vbOKCancel (MB_OKCANCEL), vbAbortRetryIgnore (MB_ABORTRETRYIGNORE), vbYesNoCancel (MB_YESNOCANCEL), vbYesNo (MB_YESNO), and vbRetryCancel (MB_RETRYCANCEL). The available icon options for VBScript are vbCritical (MB_ICONERROR), vbQuestion (MB_ICONQUESTION), vbExclamation (MB_ICONWARNING), and vbInformation (MB_ICONINFORMATION).

For example, the following call sends a msiMessageTypeError message with the vbExclamation icon and vbYesNo buttons.

Session.Message &H01000034, record

If a custom action calls the Message method, the custom action should be capable of handling a cancellation by the user and should return msiDoActionStatusUserExit.

Requirements

VersionWindows Installer 5.0 on 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, Windows XP, and Windows 2000
DLLMsi.dll
IIDIID_ISession is defined as 000C109E-0000-0000-C000-000000000046

Send comments about this topic to Microsoft

Build date: 8/13/2009

© 2009 Microsoft Corporation. All rights reserved.