PeekMessageW 函式（winuser.h）

發行項
11/20/2024

分派傳入的非佇列訊息、檢查已張貼訊息的線程消息佇列，並擷取訊息（如果有的話）。

語法

BOOL PeekMessageW(
  [out]          LPMSG lpMsg,
  [in, optional] HWND  hWnd,
  [in]           UINT  wMsgFilterMin,
  [in]           UINT  wMsgFilterMax,
  [in]           UINT  wRemoveMsg
);

參數

[out] lpMsg

類型：LPMSG

接收訊息資訊之 MSG 結構的指標。

[in, optional] hWnd

類型：HWND

要擷取其訊息的視窗句柄。窗口必須屬於目前的線程。

如果 hWnd NULL，PeekMessage 會擷取屬於目前線程的任何視窗的訊息，而目前線程 hwnd 值 NULL 的任何訊息（請參閱 msG 結構）。因此，如果 hWnd NULL，則會處理視窗訊息和線程訊息。

如果 hWnd 為 -1，PeekMessage 只會擷取目前線程消息佇列上的訊息，其 hwnd值為 NULL，也就是 PostMessage 所張貼的線程訊息（當 hWnd 參數 NULL時），或 PostThreadMessage。

[in] wMsgFilterMin

類型：UINT

要檢查之訊息範圍中第一個訊息的值。使用 WM_KEYFIRST （0x0100）來指定第一個鍵盤訊息或 WM_MOUSEFIRST （0x0200）來指定第一個滑鼠訊息。

如果 wMsgFilterMin 和 wMsgFilterMax 都是零，則 PeekMessage 會傳回所有可用的訊息（也就是不會執行範圍篩選）。

[in] wMsgFilterMax

類型：UINT

要檢查之訊息範圍中最後一則訊息的值。使用 WM_KEYLAST 來指定最後一個鍵盤訊息或 WM_MOUSELAST 來指定最後一個滑鼠訊息。

如果 wMsgFilterMin 和 wMsgFilterMax 都是零，則 PeekMessage 會傳回所有可用的訊息（也就是不會執行範圍篩選）。

[in] wRemoveMsg

類型：UINT

指定要如何處理訊息。此參數可以是下列其中一或多個值。

價值	意義
PM_NOREMOVE 0x0000	PeekMessage處理之後，訊息不會從佇列中移除。
PM_REMOVE 0x0001	PeekMessage處理之後，訊息會從佇列中移除。
PM_NOYIELD 0x0002	防止系統釋放任何等候呼叫端閑置的線程（請參閱 waitForInputIdle）。將此值與 PM_NOREMOVE 或 PM_REMOVE結合。

根據預設，會處理所有訊息類型。若要指定只應該處理特定訊息，請指定下列一或多個值。

價值	意義
PM_QS_INPUT （QS_INPUT << 16）	處理滑鼠和鍵盤訊息。
PM_QS_PAINT （QS_PAINT << 16）	處理繪製訊息。
PM_QS_POSTMESSAGE （（QS_POSTMESSAGE \|QS_HOTKEY \|QS_TIMER） << 16）	處理所有張貼的訊息，包括定時器和快捷鍵。
PM_QS_SENDMESSAGE （QS_SENDMESSAGE << 16）	處理所有已傳送的訊息。

傳回值

類型：BOOL

如果訊息可用，傳回值為非零值。

如果沒有可用的訊息，則傳回值為零。

言論

PeekMessage 會擷取與 hWnd 參數或其子系所指定的 IsChild 函式所指定之視窗相關聯的訊息，以及 wMsgFilterMin 和 wMsgFilterMax 參數所指定的訊息值範圍內。請注意，應用程式只能在 wMsgFilterMin 和 wMsgFilterMax 參數中使用低字;高字會保留給系統。

請注意，PeekMessage 一律會擷取 WM_QUIT 訊息，不論您為 wMsgFilterMin 指定哪些值，wMsgFilterMax。

在此呼叫期間，系統會使用 sendMessage、SendMessageCallback、SendMessageTimeout或 SendNotifyMessageMessage 函式傳送給呼叫線程所擁有的訊息暫止、未排入佇列的訊息。然後會擷取符合指定篩選條件的第一個佇列訊息。系統也可以處理內部事件。如果未指定任何篩選，則會依下列順序處理訊息：

已傳送訊息
張貼的訊息
輸入（硬體）訊息和系統內部事件
已傳送訊息（再次）
WM_PAINT 訊息
WM_TIMER 訊息

若要在張貼的訊息之前擷取輸入訊息，請使用 wMsgFilterMin 和 wMsgFilterMax 參數。

PeekMessage 函式通常不會從佇列中移除 WM_PAINT 訊息。 WM_PAINT 訊息會保留在佇列中，直到處理訊息為止。不過，如果 WM_PAINT 訊息具有 NULL 更新區域，PeekMessage 會將其從佇列中移除。

如果最上層視窗停止回應訊息數秒以上，系統會將視窗視為沒有回應，並將它取代為具有相同 Z 順序、位置、大小和視覺屬性的准刪除視窗。這可讓使用者移動、調整大小，或甚至關閉應用程式。不過，這些都是唯一可用的動作，因為應用程式實際上沒有回應。當應用程式進行偵錯時，系統不會產生准刪除視窗。

DPI 虛擬化

此 API 不會參與 DPI 虛擬化。輸出位於訊息目標視窗的模式中。呼叫線程不會納入考慮。

例子

如需範例，請參閱檢查消息佇列。

注意

winuser.h 標頭會將 PeekMessage 定義為別名，根據 UNICODE 預處理器常數的定義，自動選取此函式的 ANSI 或 Unicode 版本。混合使用編碼中性別名與非編碼中性的程序代碼，可能會導致編譯或運行時間錯誤不符。如需詳細資訊，請參閱函式原型的慣例。

要求

要求	價值
最低支援的用戶端	Windows 2000 Professional [僅限傳統型應用程式]
支援的最低伺服器	Windows 2000 Server [僅限傳統型應用程式]
目標平臺	窗戶
標頭	winuser.h （包括 Windows.h）
連結庫	User32.lib
DLL	User32.dll
API 集	ext-ms-win-ntuser-message-l1-1-0 （在 Windows 8 中引進）