getMessage 函式 (winuser.h)

發行項
03/13/2024

從呼叫線程的訊息佇列擷取訊息。函式會分派傳入的已傳送訊息，直到張貼的訊息可供擷取為止。

不過，PeekMessage 之類的 GetMessage 函式會封鎖 GetMessage，直到在傳回之前張貼訊息為止。

語法

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

參數

[out] lpMsg

類型： LPMSG

MSG 結構的指標，可從線程的訊息佇列接收訊息資訊。

[in, optional] hWnd

類型： HWND

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

如果 hWnd 為 NULL，GetMessage 會擷取屬於目前線程之任何視窗的訊息，以及目前線程之訊息佇列上任何訊息，其 hwnd 值為 NULL (請參閱 MSG 結構) 。因此，如果 hWnd 為 NULL，則會處理視窗訊息和線程訊息。

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

[in] wMsgFilterMin

類型： UINT

要擷取之最低訊息值的整數值。使用 WM_KEYFIRST (0x0100) 來指定第一個鍵盤訊息或 WM_MOUSEFIRST (0x0200) 來指定第一個滑鼠訊息。

使用這裡和 wMsgFilterMax 中的WM_INPUT，只指定 WM_INPUT 訊息。

如果 wMsgFilterMin 和 wMsgFilterMax 都是零， GetMessage 會傳回所有可用的訊息 (也就是說，不會執行任何範圍篩選) 。

[in] wMsgFilterMax

類型： UINT

要擷取之最高訊息值的整數值。使用 WM_KEYLAST 來指定最後一個鍵盤訊息或 WM_MOUSELAST 來指定最後一個滑鼠訊息。

使用這裡和 wMsgFilterMin 中的WM_INPUT，只指定WM_INPUT訊息。

如果 wMsgFilterMin 和 wMsgFilterMax 都是零， GetMessage 會傳回所有可用的訊息 (也就是說，不會執行任何範圍篩選) 。

傳回值

類型： BOOL

如果函式擷取 WM_QUIT以外的訊息，則傳回值為非零值。

如果函式擷取 WM_QUIT 訊息，則傳回值為零。

如果發生錯誤，則傳回值為 -1。例如，如果 hWnd 是無效的視窗句柄，或 lpMsg 是無效的指標，則函式會失敗。若要取得擴充的錯誤資訊，請呼叫 GetLastError。

因為傳回值可以是非零值、零或 -1，所以請避免像這樣的程式代碼：

while (GetMessage( lpMsg, hWnd, 0, 0)) ...

如果 hWnd 是無效的參數 (，例如參考已終結的視窗，) 表示這類程式代碼可能會導致嚴重應用程式錯誤，則 -1 傳回值的可能性。請改用如下所示的程式代碼：

BOOL bRet;

while( (bRet = GetMessage( &msg, hWnd, 0, 0 )) != 0)
{ 
    if (bRet == -1)
    {
        // handle the error and possibly exit
    }
    else
    {
        TranslateMessage(&msg); 
        DispatchMessage(&msg); 
    }
}

備註

應用程式通常會使用傳回值來判斷是否結束主要訊息循環並結束程式。

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

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

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

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

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

GetMessage 不會從佇列中移除 WM_PAINT 訊息。訊息會保留在佇列中，直到處理為止。

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

DPI 虛擬化

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

範例

如需範例，請參閱建立訊息迴圈。

規格需求

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