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 函式所使用的標準消息框樣式。 如需詳細資訊，請參閱下面的。

值 意義
INSTALLMESSAGE_FATALEXIT
 提前終止，可能嚴重記憶體不足。
INSTALLMESSAGE_ERROR
 格式化的錯誤訊息，
 
[1] 是 錯誤數據表中的訊息編號。
INSTALLMESSAGE_WARNING
 格式化的警告訊息，
 
[1] 是錯誤數據表中的訊息編號。
INSTALLMESSAGE_USER
 使用者要求訊息，
 
[1] 是錯誤數據表中的訊息編號。
INSTALLMESSAGE_INFO
 記錄的資訊訊息，
 
不顯示。
INSTALLMESSAGE_FILESINUSE
 目前使用中的檔案清單，在被取代之前必須先關閉。
INSTALLMESSAGE_RESOLVESOURCE
 判斷有效來源位置的要求。
INSTALLMESSAGE_RMFILESINUSE
 目前使用中的檔案清單，在被取代之前必須先關閉。 從 Windows Installer 4.0 版開始提供。 如需此訊息的詳細資訊，請參閱 搭配外部 UI 使用重新啟動管理員。
INSTALLMESSAGE_OUTOFDISKSPACE
 磁碟空間不足訊息。
INSTALLMESSAGE_ACTIONSTART
 進度：動作開始，
 
[1] 動作名稱，
 
[2] description，
 
[3] ACTIONDATA 訊息的範本。
INSTALLMESSAGE_ACTIONDATA
 動作數據。 記錄欄位會對應至 ACTIONSTART 訊息的範本。
INSTALLMESSAGE_PROGRESS
 進度列資訊。 請參閱下方記錄欄位的描述。
INSTALLMESSAGE_COMMONDATA
 若要啟用 [取消] 按鈕，請將 [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

另請參閱

安裝程式動作函式

使用 MsiProcessMessage 將訊息傳送至 Windows Installer