GetMessageA 函式（winuser.h）

發行項
11/20/2024

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

不同於 getMessage，PeekMessage 函式不會等候傳回之前張貼訊息。

語法

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

參數

[out] lpMsg

類型：LPMSG

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

[in, optional] hWnd

類型：HWND

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

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

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

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

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

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

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

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

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

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

DPI 虛擬化

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

例子

如需範例，請參閱建立訊息循環。

注意

winuser.h 標頭會將 GetMessage 定義為別名，根據 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 中引進）