GetMessage-Funktion (winuser.h)

Artikel
06/08/2023

Ruft eine Nachricht aus der Nachrichtenwarteschlange des aufrufenden Threads ab. Die Funktion sendet eingehende gesendete Nachrichten, bis eine gesendete Nachricht für den Abruf verfügbar ist.

GetMessage-Funktionen wie PeekMessageblockiert jedoch , bis eine Nachricht gesendet wird, bevor sie zurückgegeben wird.

Syntax

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

Parameter

[out] lpMsg

Typ: LPMSG

Ein Zeiger auf eine MSG-Struktur , die Nachrichteninformationen aus der Nachrichtenwarteschlange des Threads empfängt.

[in, optional] hWnd

Typ: HWND

Ein Handle für das Fenster, dessen Nachrichten abgerufen werden sollen. Das Fenster muss zum aktuellen Thread gehören.

Wenn hWndNULL ist, ruft GetMessage Nachrichten für jedes Fenster ab, das zum aktuellen Thread gehört, und alle Nachrichten in der Nachrichtenwarteschlange des aktuellen Threads, deren hwnd-WertNULL ist (siehe MSG-Struktur ). Wenn hWnd null ist, werden daher sowohl Fenstermeldungen als auch Threadnachrichten verarbeitet.

Wenn hWnd -1 ist, ruft GetMessage nur Nachrichten in der Nachrichtenwarteschlange des aktuellen Threads ab, deren hwnd-WertNULL ist, d. h. Threadnachrichten, die von PostMessage (wenn der hWnd-ParameterNULL ist) oder PostThreadMessage gepostet wurden.

[in] wMsgFilterMin

Typ: UINT

Der ganzzahlige Wert des niedrigsten abzurufenden Nachrichtenwerts. Verwenden Sie WM_KEYFIRST (0x0100), um die erste Tastaturnachricht oder WM_MOUSEFIRST (0x0200) anzugeben, um die erste Mausnachricht anzugeben.

Verwenden Sie WM_INPUT hier und in wMsgFilterMax , um nur die WM_INPUT Nachrichten anzugeben.

Wenn wMsgFilterMin und wMsgFilterMax beide null sind, gibt GetMessage alle verfügbaren Nachrichten zurück (d. a. es wird keine Bereichsfilterung durchgeführt).

[in] wMsgFilterMax

Typ: UINT

Der ganzzahlige Wert des höchsten abzurufenden Nachrichtenwerts. Verwenden Sie WM_KEYLAST , um die letzte Tastaturnachricht anzugeben, oder WM_MOUSELAST , um die letzte Mausnachricht anzugeben.

Verwenden Sie WM_INPUT hier und in wMsgFilterMin , um nur die WM_INPUT Nachrichten anzugeben.

Wenn wMsgFilterMin und wMsgFilterMax beide null sind, gibt GetMessage alle verfügbaren Nachrichten zurück (d. a. es wird keine Bereichsfilterung durchgeführt).

Rückgabewert

Typ: BOOL

Wenn die Funktion eine andere Nachricht als WM_QUIT abruft, ist der Rückgabewert nonzero.

Wenn die Funktion die WM_QUIT Nachricht abruft, ist der Rückgabewert 0.

Wenn ein Fehler vorliegt, ist der Rückgabewert -1. Beispielsweise schlägt die Funktion fehl, wenn hWnd ein ungültiges Fensterhandle oder lpMsg ein ungültiger Zeiger ist. Um erweiterte Fehlerinformationen zu erhalten, rufen Sie GetLastError auf.

Da der Rückgabewert nichtzero, null oder -1 sein kann, vermeiden Sie Code wie folgt:

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

Die Möglichkeit eines Rückgabewerts von -1 für den Fall, dass hWnd ein ungültiger Parameter ist (z. B. ein Fenster, das bereits zerstört wurde), bedeutet, dass dieser Code zu schwerwiegenden Anwendungsfehlern führen kann. Verwenden Sie stattdessen Code wie folgt:

BOOL bRet;

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

Hinweise

Eine Anwendung verwendet in der Regel den Rückgabewert, um zu bestimmen, ob die Standard Nachrichtenschleife beendet und das Programm beendet werden soll.

Die GetMessage-Funktion ruft Nachrichten ab, die dem Fenster zugeordnet sind, das durch den hWnd-Parameter oder eines seiner untergeordneten Elemente identifiziert wird, wie von der IsChild-Funktion angegeben, und innerhalb des Bereichs der Nachrichtenwerte, der von den Parametern wMsgFilterMin und wMsgFilterMax angegeben wird. Beachten Sie, dass eine Anwendung nur das niedrige Wort in den Parametern wMsgFilterMin und wMsgFilterMax verwenden kann. das hohe Wort ist für das System reserviert.

Beachten Sie, dass GetMessage immer WM_QUIT Nachrichten abruft, unabhängig davon, welche Werte Sie für wMsgFilterMin und wMsgFilterMax angeben.

Während dieses Aufrufs sendet das System ausstehende, nicht ausstehende Nachrichten, d. h. Nachrichten, die an Fenster gesendet werden, die dem aufrufenden Thread gehören, indem die Funktion SendMessage, SendMessageCallback, SendMessageTimeout oder SendNotifyMessage verwendet wird. Anschließend wird die erste Nachricht in der Warteschlange abgerufen, die dem angegebenen Filter entspricht. Das System kann auch interne Ereignisse verarbeiten. Wenn kein Filter angegeben ist, werden Nachrichten in der folgenden Reihenfolge verarbeitet:

Gesendete Nachrichten
Gepostete Nachrichten
Eingabenachrichten (Hardwaremeldungen) und systeminterne Ereignisse
Gesendete Nachrichten (erneut)
WM_PAINT Nachrichten
WM_TIMER Nachrichten

Verwenden Sie zum Abrufen von Eingabenachrichten vor gesendeten Nachrichten die Parameter wMsgFilterMin und wMsgFilterMax .

GetMessage entfernt WM_PAINT Nachrichten nicht aus der Warteschlange. Die Nachrichten verbleiben in der Warteschlange, bis sie verarbeitet werden.

Wenn ein Fenster der obersten Ebene länger als mehrere Sekunden nicht mehr auf Nachrichten reagiert, betrachtet das System das Fenster als nicht reagierend und ersetzt es durch ein Geisterfenster, das die gleichen Z-Reihenfolge, Position, Größe und visuellen Attribute aufweist. Dadurch kann der Benutzer sie verschieben, die Größe ändern oder sogar die Anwendung schließen. Dies sind jedoch die einzigen verfügbaren Aktionen, da die Anwendung tatsächlich nicht reagiert. Im Debuggermodus generiert das System kein Ghostfenster.

DPI-Virtualisierung

Diese API ist nicht an der DPI-Virtualisierung beteiligt. Die Ausgabe befindet sich im Modus des Fensters, auf das die Nachricht abzielt. Der aufrufende Thread wird nicht berücksichtigt.

Beispiele

Ein Beispiel finden Sie unter Erstellen einer Nachrichtenschleife.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows 2000 Professional [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows 2000 Server [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	winuser.h (einschließlich Windows.h)
Bibliothek	User32.lib
DLL	User32.dll
APIs	ext-ms-win-ntuser-message-l1-1-0 (eingeführt in Windows 8)