使用 MsiSetExternalUI 處理進度訊息
下列範例示範如何撰寫簡單的回呼處理常式，以在安裝期間接收 Windows Installer 進度訊息。
注意
當使用 MsiSetExternalUI 搭配INSTALLMESSAGE_FILESINUSE訊息類型時，傳送至外部 UI 處理常式函式的訊息不會包含 [FilesInUse] 對話方塊所使用檔案或視窗標題的任何相關資訊。 您應該使用 MsiSetExternalUIRecord 來取得資訊。
#include <windows.h>
// Globals
//
// common data information fields
int g_rgiField[3]; //array of fields to handle INSTALLOGMODE_COMMONDATA data
WORD g_wLANGID = LANG_NEUTRAL; // initialize to neutral language
//
// progress information fields
int iField[4]; //array of record fields to handle INSTALLOGMODE_PROGRESS data
int g_iProgressTotal = 0; // total ticks on progress bar
int g_iProgress = 0; // amount of progress
int iCurPos = 0;
BOOL bFirstTime = TRUE;
BOOL g_bForwardProgress = TRUE; //TRUE if the progress bar control should be incremented in a forward direction
BOOL g_bScriptInProgress = FALSE;
BOOL g_bEnableActionData; //TRUE if INSTALLOGMODE_ACTIONDATA messages are sending progress information
BOOL g_bCancelInstall = FALSE; //Should be set to TRUE if the user clicks Cancel button.
// In the following snippet, note that the internal user
// interface level is set to INSTALLLEVEL_NONE. If the internal
// user interface level is set to anything other than
// INSTALLUILEVEL_NONE, the user interface level is
// INSTALLUILEVEL_BASIC by default and the installer only
// displays an initial dialog. If the authored wizard
// sequence of the package is to be displayed, the user
// interface level should be set to INSTALLUILEVEL_FULL.
// If the external user interface handler is to have full
// control of the installation user interface, the user
// interface level must be set to INSTALLUILEVEL_NONE.
// Because an external UI handler cannot handle the
// INSTALLMESSAGE_RESOLVESOURCE message,
// Windows Installer allows a UI level,INSTALLUILEVEL_SOURCERESONLY
// that will allow an external UI handler to have full control while also still
// permitting an install to resolve the source
MsiSetInternalUI(INSTALLUILEVEL(INSTALLUILEVEL_NONE|INSTALLUILEVEL_SOURCERESONLY), NULL);
MsiSetExternalUI (TestMyBasicUIHandler,
INSTALLLOGMODE_PROGRESS|INSTALLLOGMODE_FATALEXIT|INSTALLLOGMODE_ERROR
|INSTALLLOGMODE_WARNING|INSTALLLOGMODE_USER|INSTALLLOGMODE_INFO
|INSTALLLOGMODE_RESOLVESOURCE|INSTALLLOGMODE_OUTOFDISKSPACE
|INSTALLLOGMODE_ACTIONSTART|INSTALLLOGMODE_ACTIONDATA
|INSTALLLOGMODE_COMMONDATA|INSTALLLOGMODE_PROGRESS|INSTALLLOGMODE_INITIALIZE
|INSTALLLOGMODE_TERMINATE|INSTALLLOGMODE_SHOWDIALOG,
TEXT("TEST"));
MsiInstallProduct(/*full path to package*/,NULL);
//
// FUNCTION: TestMyBasicUIHandler()
//
// PURPOSE: Demonstrates usage of an external user interface handler for MSI
//
// COMMENTS:
//
int _stdcall TestMyBasicUIHandler(LPVOID pvContext, UINT iMessageType, LPCSTR szMessage)
{
// File costing is skipped when applying Patch(es) and INSTALLUILEVEL is NONE.
// Workaround: Set INSTALLUILEVEL to anything but NONE only once.
if (bFirstTime == TRUE)
{
UINT r1 = MsiSetInternalUI(INSTALLUILEVEL_BASIC, NULL);
bFirstTime = FALSE;
}
if (!szMessage)
return 0;
INSTALLMESSAGE mt;
UINT uiFlags;
mt = (INSTALLMESSAGE)(0xFF000000 & (UINT)iMessageType);
uiFlags = 0x00FFFFFF & iMessageType;
switch (mt)
{
//Premature termination
case INSTALLMESSAGE_FATALEXIT:
/* Get fatal error message here and display it*/
return MessageBox(0, szMessage, TEXT("FatalError"), uiFlags);
case INSTALLMESSAGE_ERROR:
{
/* Get error message here and display it*/
// language and caption can be obtained from common data msg
MessageBeep(uiFlags & MB_ICONMASK);
return MessageBoxEx(0, szMessage, TEXT("Error"), uiFlags, g_wLANGID);
}
case INSTALLMESSAGE_WARNING:
/* Get warning message here and display it */
return MessageBox(0, szMessage, TEXT("Warning"), uiFlags);
case INSTALLMESSAGE_USER:
/* Get user message here */
// parse uiFlags to get Message Box Styles Flag and return appopriate value, IDOK, IDYES, etc.
return IDOK;
case INSTALLMESSAGE_INFO:
return IDOK;
case INSTALLMESSAGE_FILESINUSE:
/* Display FilesInUse dialog */
// parse the message text to provide the names of the
// applications that the user can close so that the
// files are no longer in use.
return 0;
case INSTALLMESSAGE_RESOLVESOURCE:
/* ALWAYS return 0 for ResolveSource */
return 0;
case INSTALLMESSAGE_OUTOFDISKSPACE:
/* Get user message here */
return IDOK;
case INSTALLMESSAGE_ACTIONSTART:
/* New action started, any action data is sent by this new action */
g_bEnableActionData = FALSE;
return IDOK;
case INSTALLMESSAGE_ACTIONDATA:
// only act if progress total has been initialized
if (0 == g_iProgressTotal)
return IDOK;
SetDlgItemText(/*handle to your dialog*/,/*identifier of your actiontext control*/, szMessage);
if(g_bEnableActionData)
{
SendMessage(/*handle to your progress control*/,PBM_STEPIT,0,0);
}
return IDOK;
case INSTALLMESSAGE_PROGRESS:
{
if(ParseProgressString(const_cast<LPSTR>(szMessage)))
{
// all fields off by 1 due to c array notation
switch(iField[0])
{
case 0: // Reset progress bar
{
//field 1 = 0, field 2 = total number of ticks, field 3 = direction, field 4 = in progress
/* get total number of ticks in progress bar */
g_iProgressTotal = iField[1];
/* determine direction */
if (iField[2] == 0)
g_bForwardProgress = TRUE;
else // iField[2] == 1
g_bForwardProgress = FALSE;
/* get current position of progress bar, depends on direction */
// if Forward direction, current position is 0
// if Backward direction, current position is Total # ticks
g_iProgress = g_bForwardProgress ? 0 : g_iProgressTotal;
SendMessage(/*handle to your progress control*/, PBM_SETRANGE32, 0, g_iProgressTotal);
// if g_bScriptInProgress, finish progress bar, else reset (and set up according to direction)
SendMessage(/*handle to your progress control*/, PBM_SETPOS, g_bScriptInProgress ? g_iProgressTotal : g_iProgress, 0);
iCurPos = 0;
/* determine new state */
// if new state = 1 (script in progress), could send a "Please wait..." msg
// new state = 1 means the total # of progress ticks is an estimate, and may not add up correctly
g_bScriptInProgress = (iField[3] == 1) ? TRUE : FALSE;
break;
}
case 1: // ActionInfo
{
//field 1 = 1, field 2 will contain the number of ticks to increment the bar
//ignore if field 3 is zero
if(iField[2])
{
// movement direction determined by g_bForwardProgress set by reset progress msg
SendMessage(/*handle to your progress control*/, PBM_SETSTEP, g_bForwardProgress ? iField[1] : -1*iField[1], 0);
g_bEnableActionData = TRUE;
}
else
{
g_bEnableActionData = FALSE;
}
break;
}
case 2: //ProgressReport
{
// only act if progress total has been initialized
if (0 == g_iProgressTotal)
break;
iCurPos += iField[1];
//field 1 = 2,field 2 will contain the number of ticks the bar has moved
// movement direction determined by g_bForwardProgress set by reset progress msg
SendMessage(/*handle to your progress control*/, PBM_SETPOS, g_bForwardProgress ? iCurPos : -1*iCurPos, 0);
break;
}
case 3: // ProgressAddition - fall through (we don't care to handle it -- total tick count adjustment)
default:
{
break;
}
}
}
if(g_bCancelInstall == TRUE)
{
return IDCANCEL;
}
else
return IDOK;
}
case INSTALLMESSAGE_COMMONDATA:
{
if (ParseCommonDataString(const_cast<LPSTR>(szMessage)))
{
// all fields off by 1 due to c array notation
switch (g_rgiField[0])
{
case 0:
// field 1 = 0, field 2 = LANGID, field 3 = CodePage
g_wLANGID = g_rgiField[1];
break;
case 1:
// field 1 = 1, field 2 = CAPTION
/* you could use this as the caption for MessageBoxes */
break;
case 2:
// field 1 = 2, field 2 = 0 (hide cancel button) OR 1 (show cancel button)
ShowWindow(/*handle to cancel button control on the progress indicator dialog box*/, g_rgiField[1] == 0 ? SW_HIDE : SW_SHOW);
break;
default:
break;
}
}
return IDOK;
}
// this message is received prior to internal UI initialization, no string data
case INSTALLMESSAGE_INITIALIZE:
return IDOK;
// Sent after UI termination, no string data
case INSTALLMESSAGE_TERMINATE:
return IDOK;
//Sent prior to display of authored dialog or wizard
case INSTALLMESSAGE_SHOWDIALOG:
return IDOK;
default:
return 0;
}
}
//
// FUNCTION: ParseCommonDataString(LPSTR sz)
//
// PURPOSE: Parses the common data message sent to the INSTALLUI_HANDLER callback
//
// COMMENTS: Ignores the 3rd field and the caption common data message. Assumes correct syntax.
//
BOOL ParseCommonDataString(LPSTR sz)
{
char *pch = sz;
if (0 == *pch)
return FALSE; // no msg
while (*pch != 0)
{
char chField = *pch++;
pch++; // for ':'
pch++; // for sp
switch (chField)
{
case '1': // field 1
{
// common data message type
g_rgiField[0] = *pch++ - '0';
if (g_rgiField[0] == 1)
return FALSE; // we are ignoring caption messages
break;
}
case '2': // field 2
{
// because we are ignoring caption msg, these are all ints
g_rgiField[1] = FGetInteger(pch);
return TRUE; // done processing
}
default: // unknown field
{
return FALSE;
}
}
pch++; // for space (' ') between fields
}
return TRUE;
}
//
// FUNCTION: FGetInteger(char*& pch)
//
// PURPOSE: Converts the string (from current pos. to next whitespace or '\0')
// to an integer.
//
// COMMENTS: Assumes correct syntax. Ptr is updated to new position at whitespace
// or null terminator.
//
int FGetInteger(char*& rpch)
{
char* pchPrev = rpch;
while (*rpch && *rpch != ' ')
rpch++;
*rpch = '\0';
int i = atoi(pchPrev);
return i;
}
//
// FUNCTION: ParseProgressString(LPSTR sz)
//
// PURPOSE: Parses the progress data message sent to the INSTALLUI_HANDLER callback
//
// COMMENTS: Assumes correct syntax.
//
BOOL ParseProgressString(LPSTR sz)
{
char *pch = sz;
if (0 == *pch)
return FALSE; // no msg
while (*pch != 0)
{
char chField = *pch++;
pch++; // for ':'
pch++; // for sp
switch (chField)
{
case '1': // field 1
{
// progress message type
if (0 == isdigit(*pch))
return FALSE; // blank record
iField[0] = *pch++ - '0';
break;
}
case '2': // field 2
{
iField[1] = FGetInteger(pch);
if (iField[0] == 2 || iField[0] == 3)
return TRUE; // done processing
break;
}
case '3': // field 3
{
iField[2] = FGetInteger(pch);
if (iField[0] == 1)
return TRUE; // done processing
break;
}
case '4': // field 4
{
iField[3] = FGetInteger(pch);
return TRUE; // done processing
}
default: // unknown field
{
return FALSE;
}
}
pch++; // for space (' ') between fields
}
return TRUE;
}