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
Session.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 |
|---|---|
|
-1 |
|
0 |
|
1 |
|
2 |
|
3 |
|
4 |
|
5 |
|
6 |
|
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
| Requirement | Value |
|---|---|
| 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 |
| DLL |
|
| IID |
IID_ISession is defined as 000C109E-0000-0000-C000-000000000046 |