Edit

Share via

MsiSetExternalUIA function (msi.h)

  • Article

The MsiSetExternalUI function enables an external user-interface handler. This external UI handler is called before the normal internal user-interface handler. The external UI handler has the option to suppress the internal UI by returning a non-zero value to indicate that it has handled the messages. For more information, see About the User Interface.

Syntax

INSTALLUI_HANDLERA MsiSetExternalUIA(
  [in] INSTALLUI_HANDLERA puiHandler,
  [in] DWORD              dwMessageFilter,
  [in] LPVOID             pvContext
);

Parameters

[in] puiHandler

Specifies a callback function that conforms to the INSTALLUI_HANDLER specification.

[in] dwMessageFilter

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

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
 There was 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
 Progress bar information. This message includes information on units so far and total number of units. For an explanation of the message format, see the MsiProcessMessage function. This message is only sent to an external user interface and is not logged.
INSTALLLOGMODE_INITIALIZE
 If this is not a quiet installation, then the basic UI has been 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 yet 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

Pointer to an application context that is passed to the callback function. This parameter can be used for error checking.

Return value

The return value is the previously set external handler, or zero (0) if there was no previously set handler.

Remarks

To restore the previous UI handler, second call is made to MsiSetExternalUI using the INSTALLUI_HANDLER returned by the first call to MsiSetExternalUI and specifying zero (0) for dwMessageFilter.

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 a Bootstrapping application. You cannot call MsiSetExternalUI from a custom action.

Note

The msi.h header defines MsiSetExternalUI as an alias which automatically selects the ANSI or Unicode version of this function based on the definition of the UNICODE preprocessor constant. Mixing usage of the encoding-neutral alias with code that not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For more information, see Conventions for Function Prototypes.

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. Windows Installer on Windows Server 2003 or Windows XP. 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