InitializeEmbeddedUI Callback Function

Windows Installer

InitializeEmbeddedUI Callback Function

The InitializeEmbeddedUI function prototype defines a user-defined initialization function exported by the embedded user interface DLL that is defined in the MsiEmbeddedUI table.

Syntax

C++UINT CALLBACK InitializeEmbeddedUI(
  __in     MSIHANDLE hInstall,
  __in     LPCWSTR wzResourcePath,
  __inout  LPDWORD pdwInternalUILevel
);

Parameters

hInstall [in]

A handle to the installer that performs the installation. This handle is valid only for the duration of the InitializeEmbeddedUI function.

wzResourcePath [in]

Pointer to a null-terminated string that contains the full path to the directory that contains all the files from the MsiEmbeddedUI table. The user interface DLL can use this path to load resources stored in the Windows Installer package.

pdwInternalUILevel [in, out]

Pointer to a location that contains the internal UI level.

On entry to the InitializeEmbeddedUI function, this parameter receives a value that indicates the current UI level for the installation. The value is a combination of INSTALLUILEVEL flags that notifies the UI handler whether the installation is at the full, reduced, or basic user interface levels.

The InitializeEmbeddedUI function should modify the value to one or more of the following flags. The installer resets the internal user interface level after the function returns.

Value Meaning
INSTALLUILEVEL_FULL

The embedded UI will handle some messages by using the internal Windows Installer UI set at the full user interface level.

INSTALLUILEVEL_REDUCED

The embedded UI will handle some messages by using the internal Windows Installer UI set at the reduced user interface level.

INSTALLUILEVEL_BASIC

The dialog boxes of the internal Windows Installer basic user interface are displayed together with dialog boxes of the embedded UI. The INSTALLUILEVEL_BASIC value also disables the Cancel button on the basic internal UI dialog boxes.

INSTALLUILEVEL_NONE

The embedded UI will handle all messages.

INSTALLUILEVEL_SOURCERESONLY

The embedded UI will handle all messages. If this value is combined with the INSTALLUILEVEL_NONE value, the installer displays only the dialog boxes used for source resolution. No other dialog boxes are shown. This value has no effect if the UI level is not INSTALLUILEVEL_NONE. It is used with an embedded user interface designed to handle all of the UI except for source resolution. In this case, the installer handles source resolution.

 

Return Value

The InitializeEmbeddedUI function returns the following values.

Return code Description
ERROR_SUCCESS

The embedded UI DLL initialized successfully. Messages are sent to this DLL.

INSTALLUILEVEL_NONE

The embedded UI DLL did not initialize, and the installation continues with no user interface.

INSTALLUILEVEL_BASIC

The embedded UI DLL did not initialize, and the installation continues using the internal basic user interface of the Windows Installer.

INSTALLUILEVEL_REDUCED

The embedded UI DLL did not initialize, and the installation continues using the internal reduced user interface of the Windows Installer.

INSTALLUILEVEL_FULL

The embedded UI DLL did not initialize, and the installation continues using the internal full user interface of the Windows Installer.

ERROR_INSTALL_FAILURE

The embedded UI DLL did not initialize. The installation returns ERROR_INSTALL_FAILURE.

 

Remarks

The InitializeEmbeddedUI function should not increase the internal UI level to a level above the existing internal UI level. If the function attempts to do so, the installer caps the UI level at the existing level and the installer writes a message to the log file.

For an example of the InitializeEmbeddedUI function see Using an Embedded UI.

Requirements

VersionWindows Installer 5.0 on Windows Server 2008 R2 or Windows 7. Windows Installer 4.5 on Windows Vista, Windows XP, Windows Server 2003, and Windows Server 2008
HeaderMsi.h

Build date: 8/13/2009

© 2009 Microsoft Corporation. All rights reserved.