PeekMessageA 函式 (winuser.h)

發行項
03/04/2024

分派傳入的非佇列訊息、檢查已張貼訊息的線程消息佇列，並在有任何存在時擷取訊息) (。

語法

BOOL PeekMessageA(
  [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，也就是當 hWnd 參數為 NULL) 或 PostThreadMessage 時，PostMessage 所張貼的線程訊息 (。

[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 參數中使用低字;高字會保留給系統。

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

在此呼叫期間，系統會使用 SendMessage、SendMessage、SendMessageCallback、SendMessageTimeout 或 SendNotifyMessage 函式，將傳送至呼叫線程所擁有的訊息 (DispatchMessage) 擱置、非佇列訊息。然後擷取符合指定篩選的第一個佇列訊息。系統也可能處理內部事件。如果未指定篩選條件，則會依照下列順序處理訊息：

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

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

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

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

DPI 虛擬化

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

範例

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

注意

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

規格需求

需求	值
最低支援的用戶端	Windows 2000 專業版 [僅限傳統型應用程式]
最低支援的伺服器	Windows 2000 Server [僅限傳統型應用程式]
目標平台	Windows
標頭	winuser.h (包括 Windows.h)
程式庫	User32.lib
Dll	User32.dll
API 集合	ext-ms-win-ntuser-message-l1-1-0 (於 Windows 8)