msiProcessMessage 函式 (msiquery.h)
MsiProcessMessage 函式會將錯誤記錄傳送至安裝程式進行處理。
語法
int MsiProcessMessage(
[in] MSIHANDLE hInstall,
[in] INSTALLMESSAGE eMessageType,
[in] MSIHANDLE hRecord
);
參數
[in] hInstall
處理提供給 DLL 自定義動作的安裝，或透過 MsiOpenPackage、 MsiOpenPackageEx 或 MsiOpenProduct 取得。
[in] eMessageType
eMessage 參數必須是指定下列其中一個訊息類型的值。 若要顯示具有按鈕或圖示的消息框，請使用 OR 運算符，將INSTALLMESSAGE_ERROR、INSTALLMESSAGE_WARNING或INSTALLMESSAGE_USER新增至 MessageBox 和 MessageBoxEx 函式所使用的標準消息框樣式。 如需詳細資訊，請參閱下面的。
| 值 | 意義 |
|---|---|
|
提前終止，可能嚴重記憶體不足。 |
|
格式化的錯誤訊息， |
|
格式化的警告訊息， |
|
使用者要求訊息， |
|
記錄的資訊訊息， |
|
目前使用中的檔案清單，在被取代之前必須先關閉。 |
|
判斷有效來源位置的要求。 |
|
目前使用中的檔案清單，在被取代之前必須先關閉。 從 Windows Installer 4.0 版開始提供。 如需此訊息的詳細資訊，請參閱 搭配外部 UI 使用重新啟動管理員。 |
|
磁碟空間不足訊息。 |
|
進度：動作開始， |
|
動作數據。 記錄欄位會對應至 ACTIONSTART 訊息的範本。 |
|
進度列資訊。 請參閱下方記錄欄位的描述。 |
|
若要啟用 [取消] 按鈕，請將 [1] 設定為 2，並將 [2] 設定為 1。
停用 [取消] 按鈕將 [1] 設定為 2，並將 [2] 設為 0 |
[in] hRecord
包含訊息格式和數據之記錄的句柄。
傳回值
此函式會傳回 int。
備註
MsiProcessMessage 函式會執行任何已啟用的記錄作業，並延遲執行。 您可以選擇性地啟用各種訊息類型的記錄。
針對INSTALLMESSAGE_FATALEXIT，如果字段 0 未設定欄位 1，則INSTALLMESSAGE_ERROR、INSTALLMESSAGE_WARNING和INSTALLMESSAGE_USER訊息必須設定為對應至 Error 數據表中錯誤訊息的錯誤碼。 然後，訊息會先使用 Error 數據表中的範本格式化，再將它傳遞至使用者介面處理程式以供顯示。
進度列訊息的記錄欄位
下列描述 eMessageType 設定為 INSTALLMESSAGE_PROGRESS 時的記錄字段。 欄位 1 會指定進度訊息的類型。 其他欄位的意義取決於此欄位中的值。 可以設定為欄位 1 的可能值如下所示。| 欄位 1 值 | 欄位 1 描述 |
|---|---|
| 0 | 重設進度列，並設定列中預期的刻度總數。 |
| 1 | 提供與目前動作所傳送之進度訊息相關的資訊。 |
| 2 | 遞增進度列。 |
| 3 | 啟用動作 (，例如 CustomAction) ，將刻度新增至進度列的預期進度總數。 |
Field 2 的意義取決於字段 1 中的值，如下所示。
| 欄位 1 值 | 欄位 2 描述 |
|---|---|
| 0 | 進度列中預期的刻度總數。 |
| 1 | 進度列針對目前動作所傳送的每個 ActionData 訊息行動的刻度數目。 如果欄位 3 為 0，則會忽略此欄位。 |
| 2 | 進度列已移動的刻度數目。 |
| 3 | 要新增至預期進度總計的刻度數目。 |
Field 3 的意義取決於字段 1 中的值，如下所示。
| 欄位 1 值 | 欄位 3 值 | 欄位 3 描述 |
|---|---|---|
| 0 | 0 | 向前進度列 (由左至右) |
| 1 | 向後進度列 (由右至左) | |
| 1 | 0 | 目前的動作會傳送明確的 ProgressReport 訊息。 |
| 1 | 每次由目前動作傳送 ActionData 訊息時，依 Field 2 中指定的刻度數遞增進度列。 | |
| 2 | 未使用 | |
| 3 | 未使用 |
Field 4 的意義取決於 Field 1 中的值，如下所示。
| 欄位 1 值 | 欄位 4 值 | 欄位 4 描述 |
|---|---|---|
| 0 | 0 | 執行正在進行中。 在此情況下，UI 可以計算並顯示剩餘的時間。 |
| 1 | 建立執行腳本。 在此情況下，UI 可能會顯示訊息，以在安裝程式完成安裝準備時等候。 | |
| 1 | 未使用 | |
| 2 | 未使用 | |
| 3 | 未使用 |
如需詳細資訊和程式代碼範例，請參閱 將自定義動作新增至 ProgressBar。
消息框的顯示
若要顯示具有按鈕或圖示的消息框，請使用 OR 運算符，搭配 MessageBox 和 MessageBoxEx 所使用的消息框選項來新增INSTALLMESSAGE_ERROR、INSTALLMESSAGE_WARNING或INSTALLMESSAGE_USER。 可用的按鈕選項包括MB_OK、MB_OKCANCEL、MB_ABORTRETRYIGNORE、MB_YESNOCANCEL、MB_YESNO和MB_RETRYCANCEL。 可用的預設按鈕選項是MB_DEFBUTTON1、MB_DEFBUTTON2和MB_DEFBUTTON3。 可用的圖示選項包括MB_ICONERROR、MB_ICONQUESTION、MB_ICONWARNING和MB_ICONINFORMATION。 如果未指定任何圖示選項，Windows Installer 會根據訊息類型選擇預設圖示樣式。例如，下列 MsiProcessMessage 呼叫會傳送具有MB_ICONWARNING圖示和MB_ABORTRETRYCANCEL按鈕的INSTALLMESSAGE_ERROR訊息。
PMSIHANDLE hInstall;
PMSIHANDLE hRec;
MsiProcessMessage(hInstall,
INSTALLMESSAGE(INSTALLMESSAGE_ERROR|MB_ABORTRETRYIGNORE|MB_ICONWARNING),
hRec);
如果自定義動作呼叫 MsiProcessMessage，自定義動作應該能夠由用戶處理取消，而且應該傳回ERROR_INSTALL_USEREXIT。
如需使用 MsiProcessMessage 傳送訊息的詳細資訊，請參閱 使用 MsiProcessMessage 將訊息傳送至 Windows 安裝程式。
規格需求
| 需求 | 值 |
|---|---|
| 最低支援的用戶端 | Windows Server 2012、Windows 8、Windows Server 2008 R2 或 Windows 7 上的 Windows Installer 5.0。 Windows Server 2008 或 Windows Vista 上的 Windows Installer 4.0 或 Windows Installer 4.5。 Windows Server 2003 或 Windows XP 上的 Windows Installer |
| 目標平台 | Windows |
| 標頭 | msiquery.h |
| 程式庫 | Msi.lib |
| Dll | Msi.dll |