GetMessageW-Funktion (winuser.h)

Artikel
11/20/2024

Ruft eine Nachricht aus der Nachrichtenwarteschlange des aufrufenden Threads ab. Die Funktion sendet eingehende gesendete Nachrichten, bis eine gepostete Nachricht zum Abrufen verfügbar ist.

Im Gegensatz zu GetMessage-wartet die PeekMessage--Funktion nicht, bis eine Nachricht gepostet wird, bevor sie zurückgegeben wird.

Syntax

BOOL GetMessageW(
  [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 hWndNULList, 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 Wert NULL ist (siehe MSG Struktur). Wenn hWnd NULL-ist, werden daher sowohl Fensternachrichten als auch Threadnachrichten verarbeitet.

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

[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 null sind, gibt GetMessage alle verfügbaren Nachrichten zurück (d. a. es wird keine Bereichsfilterung ausgeführt).

[in] wMsgFilterMax

Typ: UINT-

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

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

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

Rückgabewert

Typ: BOOL-

Wenn die Funktion eine andere Nachricht als WM_QUITabruft, ist der Rückgabewert ungleich Null.

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

Wenn ein Fehler auftritt, lautet der Rückgabewert -1. Die Funktion schlägt z. B. fehl, wenn hWnd ein ungültiges Fensterhandle ist oder lpMsg ein ungültiger Zeiger ist. Rufen Sie GetLastErrorauf, um erweiterte Fehlerinformationen zu erhalten.

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

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

Die Möglichkeit eines -1 Rückgabewerts für den Fall, dass hWnd ein ungültiger Parameter ist (z. B. das Verweisen auf ein bereits zerstörtes Fenster), bedeutet, dass ein solcher 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); 
    }
}

Bemerkungen

Eine Anwendung verwendet in der Regel den Rückgabewert, um zu bestimmen, ob die Hauptnachrichtenschleife 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 durch die funktion IsChild angegeben, und innerhalb des Bereichs der Nachrichtenwerte, die durch die wMsgFilterMin und wMsgFilterMax Parameter angegeben werden. Beachten Sie, dass eine Anwendung nur das niedrige Wort im wMsgFilterMin- und wMsgFilterMax Parameter 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 wMsgFilterMaxangeben.

Während dieses Aufrufs übermittelt das System ausstehende, nicht abgefragte Nachrichten, d. h. Nachrichten, die an Fenster gesendet werden, die dem aufrufenden Thread gehören, mithilfe der SendMessage-, SendMessageCallback-, SendMessageTimeout-oder SendNotifyMessage-Funktion. Anschließend wird die erste nachricht in die Warteschlange gestellt, 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
Eingabemeldungen (Hardware) und interne Systemereignisse
Gesendete Nachrichten (erneut)
WM_PAINT Nachrichten
WM_TIMER Nachrichten

Verwenden Sie zum Abrufen von Eingabemeldungen vor geposteten Nachrichten die parameter wMsgFilterMin und wMsgFilterMax.

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

Wenn ein Fenster auf oberster Ebene länger als mehrere Sekunden nicht mehr auf Nachrichten reagiert, berücksichtigt das System, dass das Fenster nicht reagiert und durch ein Geisterfenster ersetzt wird, das die gleiche Z-Reihenfolge, Position, Größe und visuelle Attribute aufweist. Auf diese Weise kann der Benutzer sie verschieben, seine Größe ändern oder die Anwendung sogar schließen. Dies sind jedoch die einzigen Verfügbaren Aktionen, da die Anwendung tatsächlich nicht reagiert. Im Debuggermodus generiert das System kein Geisterfenster.

DPI-Virtualisierung

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

Beispiele

Ein Beispiel finden Sie unter Erstellen einer Nachrichtenschleife.

Anmerkung

Der winuser.h-Header definiert GetMessage als Alias, der automatisch die ANSI- oder Unicode-Version dieser Funktion basierend auf der Definition der UNICODE-Präprozessorkonstante auswählt. Das Mischen der Verwendung des codierungsneutralen Alias mit Code, der nicht codierungsneutral ist, kann zu Nichtübereinstimmungen führen, die zu Kompilierungs- oder Laufzeitfehlern führen. Weitere Informationen finden Sie unter Konventionen für Funktionsprototypen.

Anforderungen

Anforderung	Wert
mindestens unterstützte Client-	Windows 2000 Professional [nur Desktop-Apps]
mindestens unterstützte Server-	Windows 2000 Server [nur Desktop-Apps]
Zielplattform-	Fenster
Header-	winuser.h (enthalten Windows.h)
Library	User32.lib
DLL-	User32.dll
API-Satz	ext-ms-win-ntuser-message-l1-1-0 (eingeführt in Windows 8)