PeekMessageW-Funktion (winuser.h)

Artikel
08/27/2023

Sendet eingehende nicht queuierte Nachrichten, überprüft die Threadnachrichtenwarteschlange auf eine gesendete Nachricht und ruft die Nachricht ab (falls vorhanden).

Syntax

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

Parameter

[out] lpMsg

Typ: LPMSG

Ein Zeiger auf eine MSG-Struktur , die Nachrichteninformationen 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 PeekMessage 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 PeekMessage 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 Wert der ersten Nachricht im Bereich der zu untersuchenden Nachrichten. Verwenden Sie WM_KEYFIRST (0x0100), um die erste Tastaturnachricht oder WM_MOUSEFIRST (0x0200) anzugeben, um die erste Mausnachricht anzugeben.

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

[in] wMsgFilterMax

Typ: UINT

Der Wert der letzten Nachricht im Bereich der zu untersuchenden Nachrichten. Verwenden Sie WM_KEYLAST , um die letzte Tastaturnachricht anzugeben, oder WM_MOUSELAST , um die letzte Mausnachricht anzugeben.

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

[in] wRemoveMsg

Typ: UINT

Gibt an, wie Nachrichten behandelt werden sollen. Dieser Parameter kann einen oder mehrere der folgenden Werte aufweisen.

Wert	Bedeutung
PM_NOREMOVE 0x0000	Nachrichten werden nach der Verarbeitung durch PeekMessage nicht aus der Warteschlange entfernt.
PM_REMOVE 0x0001	Nachrichten werden nach der Verarbeitung durch PeekMessage aus der Warteschlange entfernt.
PM_NOYIELD 0x0002	Verhindert, dass das System einen Thread freigibt, der darauf wartet, dass der Aufrufer in den Leerlauf wechselt (siehe WaitForInputIdle). Kombinieren Sie diesen Wert mit PM_NOREMOVE oder PM_REMOVE.

Standardmäßig werden alle Nachrichtentypen verarbeitet. Um anzugeben, dass nur bestimmte Nachrichten verarbeitet werden sollen, geben Sie mindestens einen der folgenden Werte an.

Wert	Bedeutung
PM_QS_INPUT (QS_INPUT << 16)	Verarbeiten von Maus- und Tastaturnachrichten.
PM_QS_PAINT (QS_PAINT << 16)	Verarbeiten von Malnachrichten.
PM_QS_POSTMESSAGE ((QS_POSTMESSAGE \| QS_HOTKEY \| QS_TIMER) << 16)	Verarbeiten Sie alle gesendeten Nachrichten, einschließlich Timern und Hotkeys.
PM_QS_SENDMESSAGE (QS_SENDMESSAGE << 16)	Verarbeiten sie alle gesendeten Nachrichten.

Rückgabewert

Typ: BOOL

Wenn eine Nachricht verfügbar ist, ist der Rückgabewert nonzero.

Wenn keine Nachrichten verfügbar sind, ist der Rückgabewert 0.

Hinweise

PeekMessage ruft Nachrichten ab, die dem Fenster zugeordnet sind, das durch den hWnd-Parameter oder eine 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 PeekMessage 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 Nachrichten (DispatchMessage), 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 .

Die PeekMessage-Funktion entfernt normalerweise keine WM_PAINT Nachrichten aus der Warteschlange. WM_PAINT Nachrichten bleiben in der Warteschlange, bis sie verarbeitet werden. Wenn eine WM_PAINT Nachricht jedoch über einen NULL-Updatebereich verfügt, entfernt PeekMessage sie aus der Warteschlange.

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. Wenn eine Anwendung debuggen wird, 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 Untersuchen einer Nachrichtenwarteschlange.

Hinweis

Der winuser.h-Header definiert PeekMessage als Alias, der die ANSI- oder Unicode-Version dieser Funktion basierend auf der Definition der UNICODE-Präprozessorkonstante automatisch auswählt. Das Mischen der Verwendung des codierungsneutralen Alias mit nicht codierungsneutralem Code 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
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)