SetWindowsHookExA-Funktion (winuser.h)

Artikel
07/01/2023

Installiert eine anwendungsdefinierte Hookprozedur in einer Hookkette. Sie würden eine Hookprozedur installieren, um das System auf bestimmte Arten von Ereignissen zu überwachen. Diese Ereignisse sind entweder einem bestimmten Thread oder allen Threads auf demselben Desktop wie der aufrufende Thread zugeordnet.

Syntax

HHOOK SetWindowsHookExA(
  [in] int       idHook,
  [in] HOOKPROC  lpfn,
  [in] HINSTANCE hmod,
  [in] DWORD     dwThreadId
);

Parameter

[in] idHook

Typ: int

Der Typ der zu installierenden Hookprozedur. Dieser Parameter kann einen der folgenden Werte annehmen.

Wert	Bedeutung
WH_CALLWNDPROC 4	Installiert eine Hookprozedur, die Nachrichten überwacht, bevor das System sie an die Zielfensterprozedur sendet. Weitere Informationen finden Sie in der CallWindowProcW-Funktionshookprozedur/CallWindowProcA .
WH_CALLWNDPROCRET 12	Installiert eine Hookprozedur, die Nachrichten überwacht, nachdem sie von der Zielfensterprozedur verarbeitet wurden. Weitere Informationen finden Sie in der Hookprozedur [HOOKPROC-Rückruffunktion](nc-winuser-hookproc.md).
WH_CBT 5	Installiert eine Hookprozedur, die Benachrichtigungen empfängt, die für eine CBT-Anwendung nützlich sind. Weitere Informationen finden Sie in der CBTProc-Hookprozedur .
WH_DEBUG 9	Installiert eine Hookprozedur, die zum Debuggen anderer Hookprozeduren nützlich ist. Weitere Informationen finden Sie in der DebugProc-Hookprozedur .
WH_FOREGROUNDIDLE 11	Installiert eine Hookprozedur, die aufgerufen wird, wenn sich der Vordergrundthread der Anwendung im Leerlauf befindet. Dieser Hook ist nützlich, um Aufgaben mit niedriger Priorität während der Leerlaufzeit auszuführen. Weitere Informationen finden Sie in der Hookprozedur ForegroundIdleProc .
WH_GETMESSAGE 3	Installiert eine Hookprozedur, die Nachrichten überwacht, die an eine Nachrichtenwarteschlange gesendet werden. Weitere Informationen finden Sie in der Hookprozedur GetMsgProc .
WH_JOURNALPLAYBACK 1	Warnung Windows 11 und neuer: Journaling Hook-APIs werden nicht unterstützt. Es wird empfohlen, stattdessen die SendInput TextInput-API zu verwenden. Installiert eine Hookprozedur, die zuvor von einer WH_JOURNALRECORD Hookprozedur aufgezeichnete Nachrichten veröffentlicht. Weitere Informationen finden Sie in der Hookprozedur JournalPlaybackProc .
WH_JOURNALRECORD 0	Warnung Windows 11 und neuer: Journaling Hook-APIs werden nicht unterstützt. Es wird empfohlen, stattdessen die SendInput TextInput-API zu verwenden. Installiert eine Hookprozedur, die Eingabenachrichten aufzeichnet, die an die Systemnachrichtenwarteschlange gesendet werden. Dieser Hook ist nützlich für die Aufzeichnung von Makros. Weitere Informationen finden Sie in der Hookprozedur JournalRecordProc .
WH_KEYBOARD 2	Installiert eine Hookprozedur, die Tastatureingabemeldungen überwacht. Weitere Informationen finden Sie unter KeyboardProc-Hookprozedur .
WH_KEYBOARD_LL 13	Installiert eine Hookprozedur, die Tastatureingabeereignisse auf niedriger Ebene überwacht. Weitere Informationen finden Sie in der Hookprozedur [LowLevelKeyboardProc](/windows/win32/winmsg/lowlevelkeyboardproc).
WH_MOUSE 7	Installiert eine Hookprozedur, die Mausnachrichten überwacht. Weitere Informationen finden Sie unter MouseProc-Hookprozedur .
WH_MOUSE_LL 14	Installiert eine Hookprozedur, die Mauseingabeereignisse auf niedriger Ebene überwacht. Weitere Informationen finden Sie in der Hookprozedur LowLevelMouseProc .
WH_MSGFILTER -1	Installiert eine Hookprozedur, die nachrichten überwacht, die als Ergebnis eines Eingabeereignisses in einem Dialogfeld, Meldungsfeld, Menü oder Einer Bildlaufleiste generiert werden. Weitere Informationen finden Sie in der Hookprozedur MessageProc .
WH_SHELL 10	Installiert eine Hookprozedur, die Benachrichtigungen empfängt, die für Shellanwendungen nützlich sind. Weitere Informationen finden Sie in der ShellProc-Hookprozedur .
WH_SYSMSGFILTER 6	Installiert eine Hookprozedur, die nachrichten überwacht, die als Ergebnis eines Eingabeereignisses in einem Dialogfeld, Meldungsfeld, Menü oder Einer Bildlaufleiste generiert werden. Die Hookprozedur überwacht diese Meldungen für alle Anwendungen auf demselben Desktop wie der aufrufende Thread. Weitere Informationen finden Sie in der Hookprozedur SysMsgProc .

[in] lpfn

Typ: HOOKPROC

Ein Zeiger auf die Hookprozedur. Wenn der dwThreadId-Parameter null ist oder den Bezeichner eines Threads angibt, der von einem anderen Prozess erstellt wurde, muss der lpfn-Parameter auf eine Hookprozedur in einer DLL verweisen. Andernfalls kann lpfn auf eine Hookprozedur im Code verweisen, der dem aktuellen Prozess zugeordnet ist.

[in] hmod

Typ: HINSTANCE

Ein Handle für die DLL, das die Hookprozedur enthält, auf die der lpfn-Parameter verweist. Der hMod-Parameter muss auf NULL festgelegt werden, wenn der dwThreadId-Parameter einen vom aktuellen Prozess erstellten Thread angibt und sich die Hookprozedur innerhalb des dem aktuellen Prozess zugeordneten Codes befindet.

[in] dwThreadId

Art: DWORD

Der Bezeichner des Threads, dem die Hookprozedur zugeordnet werden soll. Wenn dieser Parameter für Desktop-Apps null ist, wird die Hookprozedur allen vorhandenen Threads zugeordnet, die auf demselben Desktop wie der aufrufende Thread ausgeführt werden. Informationen zu Windows Store-Apps finden Sie im Abschnitt Hinweise.

Rückgabewert

Typ: HHOOK

Wenn die Funktion erfolgreich ist, ist der Rückgabewert das Handle für die Hookprozedur.

Wenn bei der Funktion ein Fehler auftritt, ist der Rückgabewert NULL. Um erweiterte Fehlerinformationen zu erhalten, rufen Sie GetLastError auf.

Hinweise

SetWindowsHookEx kann verwendet werden, um eine DLL in einen anderen Prozess einzufügen. Eine 32-Bit-DLL kann nicht in einen 64-Bit-Prozess eingefügt werden, und eine 64-Bit-DLL kann nicht in einen 32-Bit-Prozess eingefügt werden. Wenn eine Anwendung die Verwendung von Hooks in anderen Prozessen erfordert, muss eine 32-Bit-Anwendung SetWindowsHookEx aufrufen, um eine 32-Bit-DLL in 32-Bit-Prozesse einzufügen, und eine 64-Bit-Anwendung ruft SetWindowsHookEx auf, um eine 64-Bit-DLL in 64-Bit-Prozesse einzufügen. Die 32-Bit- und 64-Bit-DLLs müssen unterschiedliche Namen aufweisen.

Da Hooks im Kontext einer Anwendung ausgeführt werden, müssen sie mit der "Bitanzahl" der Anwendung übereinstimmen. Wenn eine 32-Bit-Anwendung einen globalen Hook unter 64-Bit-Windows installiert, wird der 32-Bit-Hook in jeden 32-Bit-Prozess eingefügt (die üblichen Sicherheitsgrenzen gelten). In einem 64-Bit-Prozess werden die Threads weiterhin als "hooked" markiert. Da jedoch eine 32-Bit-Anwendung den Hookcode ausführen muss, führt das System den Hook im Kontext der Hooking-App aus. insbesondere für den Thread, der SetWindowsHookEx aufgerufen hat. Dies bedeutet, dass die Hookinganwendung weiterhin Nachrichten pumpen muss, da sie sonst die normale Funktion der 64-Bit-Prozesse blockieren kann.

Wenn eine 64-Bit-Anwendung einen globalen Hook unter 64-Bit-Windows installiert, wird der 64-Bit-Hook in jeden 64-Bit-Prozess eingefügt, während alle 32-Bit-Prozesse einen Rückruf für die Hookinganwendung verwenden.

Um alle Anwendungen auf dem Desktop einer 64-Bit-Windows-Installation zu hooken, installieren Sie einen globalen 32-Bit-Hook und einen 64-Bit-globalen Hook, die jeweils von entsprechenden Prozessen stammen, und stellen Sie sicher, dass Sie weiterhin Nachrichten in die Hookinganwendung pumpen, um zu verhindern, dass die normale Funktion blockiert wird. Wenn Sie bereits über eine globale 32-Bit-Hookinganwendung verfügen und diese nicht im Kontext jeder Anwendung ausgeführt werden muss, müssen Sie möglicherweise keine 64-Bit-Version erstellen.

Ein Fehler kann auftreten, wenn der hMod-ParameterNULL ist und der dwThreadId-Parameter null ist oder den Bezeichner eines Threads angibt, der von einem anderen Prozess erstellt wurde.

Das Aufrufen der CallNextHookEx-Funktionsfunktion zum Verketten mit der nächsten Hookprozedur ist optional, wird jedoch dringend empfohlen. Andernfalls erhalten andere Anwendungen, die Hooks installiert haben, keine Hookbenachrichtigungen und verhalten sich daher möglicherweise falsch. Sie sollten CallNextHookEx aufrufen, es sei denn, Sie müssen unbedingt verhindern, dass die Benachrichtigung von anderen Anwendungen angezeigt wird.

Vor dem Beenden muss eine Anwendung die Funktion UnhookWindowsHookEx aufrufen, um systemressourcen freizugeben, die dem Hook zugeordnet sind.

Der Bereich eines Hooks hängt vom Hooktyp ab. Einige Hooks können nur mit einem globalen Bereich festgelegt werden. Andere können auch nur für einen bestimmten Thread festgelegt werden, wie in der folgenden Tabelle gezeigt.

Hook	`Scope`
WH_CALLWNDPROC	Thread oder global
WH_CALLWNDPROCRET	Thread oder global
WH_CBT	Thread oder global
WH_DEBUG	Thread oder global
WH_FOREGROUNDIDLE	Thread oder global
WH_GETMESSAGE	Thread oder global
WH_JOURNALPLAYBACK	Nur global
WH_JOURNALRECORD	Nur global
WH_KEYBOARD	Thread oder global
WH_KEYBOARD_LL	Nur global
WH_MOUSE	Thread oder global
WH_MOUSE_LL	Nur global
WH_MSGFILTER	Thread oder global
WH_SHELL	Thread oder global
WH_SYSMSGFILTER	Nur global

Für einen angegebenen Hooktyp werden zuerst Threadhooks und dann globale Hooks aufgerufen. Beachten Sie, dass die Hooks WH_MOUSE, WH_KEYBOARD, WH_JOURNAL*, WH_SHELL und Hooks auf niedriger Ebene für den Thread aufgerufen werden können, der den Hook installiert hat, und nicht für den Thread, der den Hook verarbeitet. Für diese Hooks ist es möglich, dass sowohl der 32-Bit- als auch der 64-Bit-Hook aufgerufen wird, wenn ein 32-Bit-Hook vor einem 64-Bit-Hook in der Hookkette steht.

Die globalen Hooks sind eine freigegebene Ressource, und die Installation wirkt sich auf alle Anwendungen auf demselben Desktop wie der aufrufende Thread aus. Alle globalen Hookfunktionen müssen sich in Bibliotheken befinden. Globale Hooks sollten auf spezielle Anwendungen oder als Entwicklungshilfe beim Debuggen von Anwendungen beschränkt werden. Bibliotheken, die keinen Hook mehr benötigen, sollten ihre Hookprozedur entfernen.

Entwicklung von Windows Store-Apps Wenn dwThreadId 0 ist, werden Fensterhook-DLLs für die Windows Store-App-Prozesse und den Windows-Runtime Brokerprozess nicht in den Prozess geladen, es sei denn, sie werden von einem uiAccess-Prozess (Barrierefreiheitstools) installiert. Die Benachrichtigung wird im Thread des Installationsprogramms für diese Hooks übermittelt:

WH_JOURNALPLAYBACK
WH_JOURNALRECORD
WH_KEYBOARD
WH_KEYBOARD_LL
WH_MOUSE
WH_MOUSE_LL

Dieses Verhalten ähnelt dem, was passiert, wenn ein Architekturkonflikt zwischen der Hook-DLL und dem Zielanwendungsprozess besteht, z. B. wenn die Hook-DLL 32-Bit und der Anwendungsprozess 64-Bit ist.

Beispiele

Ein Beispiel finden Sie unter Installieren und Freigeben von Hookprozeduren.

Hinweis

Der winuser.h-Header definiert SetWindowsHookEx 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 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


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 (windows.h einschließen)
Bibliothek	User32.lib
DLL	User32.dll
APIs	ext-ms-win-ntuser-window-l1-1-0 (eingeführt in Windows 8)