MsiSetExternalUIRecord function (msi.h)

The MsiSetExternalUIRecord function enables an external user-interface (UI) handler.

Syntax

UINT MsiSetExternalUIRecord(
  [in]            INSTALLUI_HANDLER_RECORD  puiHandler,
  [in]            DWORD                     dwMessageFilter,
  [in]            LPVOID                    pvContext,
  [out, optional] PINSTALLUI_HANDLER_RECORD ppuiPrevHandler
);

Parameters

[in] puiHandler

Specifies a callback function that conforms to the INSTALLUI_HANDLER_RECORD specification.

To disable the current external UI handler, call the function with this parameter set to a NULL value.

[in] dwMessageFilter

Specifies which messages to handle using the external message handler. If the external handler returns a non-zero result, then that message is not sent to the UI, instead the message is logged if logging is enabled. For more information, see MsiEnableLog.

Value Meaning
INSTALLLOGMODE_FILESINUSE
Files in use information.

When this message is received, a FilesInUse Dialog should be displayed.

INSTALLLOGMODE_FATALEXIT
Premature termination of installation.
INSTALLLOGMODE_ERROR
The error messages are logged.
INSTALLLOGMODE_WARNING
The warning messages are logged.
INSTALLLOGMODE_USER
The user requests are logged.
INSTALLLOGMODE_INFO
The status messages that are not displayed are logged.
INSTALLLOGMODE_RESOLVESOURCE
Request to determine a valid source location.
INSTALLLOGMODE_RMFILESINUSE
Files in use information. When this message is received, a MsiRMFilesInUse Dialog should be displayed.
INSTALLLOGMODE_OUTOFDISKSPACE
The is insufficient disk space.
INSTALLLOGMODE_ACTIONSTART
The start of new installation actions are logged.
INSTALLLOGMODE_ACTIONDATA
The data record with the installation action is logged.
INSTALLLOGMODE_COMMONDATA
The parameters for user-interface initialization are logged.
INSTALLLOGMODE_PROGRESS
The Progress bar information.

This message includes information about units so far and total number of units. This message is only sent to an external user interface and is not logged. For more information, see MsiProcessMessage.

INSTALLLOGMODE_INITIALIZE
If this is not a quiet installation, then the basic UI is initialized.

If this is a full UI installation, the Full UI is not yet initialized.

This message is only sent to an external user interface and is not logged.

INSTALLLOGMODE_TERMINATE
If a full UI is being used, the full UI has ended.

If this is not a quiet installation, the basic UI has not ended.

This message is only sent to an external user interface and is not logged.

INSTALLLOGMODE_SHOWDIALOG
Sent prior to display of the Full UI dialog.

This message is only sent to an external user interface and is not logged.

INSTALLLOGMODE_INSTALLSTART
Installation of product begins.

The message contains the product's ProductName and ProductCode.

INSTALLLOGMODE_INSTALLEND
Installation of product ends.

The message contains the product's ProductName, ProductCode, and return value.

[in] pvContext

A pointer to an application context that is passed to the callback function.

This parameter can be used for error checking.

[out, optional] ppuiPrevHandler

Returns the pointer to the previously set callback function that conforms to the INSTALLUI_HANDLER_RECORD specification, or NULL if no callback is previously set.

Return value

Return code Description
ERROR_SUCCESS
The function completes successfully.
ERROR_CALL_NOT_IMPLEMENTED
This value indicates that an attempt is made to call this function from a custom action.

This function cannot be called from a custom action.

Remarks

This function cannot be called from Custom Actions.

The external UI handler enabled by calling MsiSetExternalUIRecord receives messages in the format of a Record Object. The external UI handler enabled by calling MsiSetExternalUI receives messages in the format of a string. An external UI is always called before the Windows Installer internal UI. An enabled record-based external UI is called before any string-based external UI. If the record-based external UI handler returns 0 (zero), the message is sent to any enabled string-based external UI handler. If the external UI handler returns a non-zero value, the internal Windows Installer UI handler is suppressed and the messages are considered handled.

This function stores the external user interfaces it has set. To replace the current external UI handler with a previous handler, call the function and specify the INSTALLUI_HANDLER_RECORD as the puiHandler parameter and 0 (zero) as the dwMessageFilter parameter.

The external user interface handler pointed to by the puiHandler parameter does not have full control over the external user interface unless MsiSetInternalUI is called with the dwUILevel parameter set to INSTALLUILEVEL_NONE. If MsiSetInternalUI is not called, the internal user interface level defaults to INSTALLUILEVEL_BASIC. As a result, any message not handled by the external user interface handler is handled by Windows Installer. The initial "Preparing to install. . ." dialog always appears even if the external user interface handler handles all messages. MsiSetExternalUI should only be called from an Bootstrapping application. You cannot call MsiSetExternalUI from a custom action.

To disable this external UI handler, call MsiSetExternalUIRecord with a NULL value for the puiHandler parameter.

Windows Installer 2.0 and Windows Installer 3.0:  Not supported. The MsiSetExternalUIRecord function is available beginning with Windows Installer 3.1.

For more information about using a record-based external handler, see Monitoring an Installation Using MsiSetExternalUIRecord.

Requirements

Requirement Value
Minimum supported client 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. See the Windows Installer Run-Time Requirements for information about the minimum Windows service pack that is required by a Windows Installer version.
Target Platform Windows
Header msi.h
Library Msi.lib
DLL Msi.dll

See also

Interface and Logging Functions

Not Supported in Windows Installer 3.0 and earlier