SetWindowsHookExA-Funktion (winuser.h)

Artikel
11/18/2024

Installiert ein anwendungsdefiniertes Hook-Verfahren in einer Hookchain. Sie würden eine Hook-Prozedur installieren, um das System auf bestimmte Ereignistypen zu überwachen. Diese Ereignisse werden 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 des zu installierenden Hook-Verfahrens. Dieser Parameter kann einer der folgenden Werte sein:

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

[in] lpfn

Typ: HOOKPROC-

Ein Zeiger auf die Hook-Prozedur. 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 Hook-Prozedur in einer DLL verweisen. Andernfalls kann lpfn auf eine Hook-Prozedur im Code verweisen, der dem aktuellen Prozess zugeordnet ist.

[in] hmod

Typ: HINSTANCE-

Ein Handle für die DLL, die die Hook-Prozedur enthält, auf die der lpfn Parameter verweist. Der hMod--Parameter muss auf NULL- festgelegt werden, wenn der parameter dwThreadId einen thread angibt, der vom aktuellen Prozess erstellt wurde und wenn sich die Hook-Prozedur im Code befindet, der dem aktuellen Prozess zugeordnet ist.

[in] dwThreadId

Typ: DWORD-

Der Bezeichner des Threads, dem die Hook-Prozedur zugeordnet werden soll. Wenn dieser Parameter null ist, wird die Hook-Prozedur für Desktop-Apps 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 der Handle für die Hook-Prozedur.

Wenn die Funktion fehlschlägt, ist der Rückgabewert NULL-. Rufen Sie GetLastErrorauf, um erweiterte Fehlerinformationen zu erhalten.

Bemerkungen

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, ist es erforderlich, dass ein 32-Bit-Anwendungsaufruf SetWindowsHookEx eine 32-Bit-DLL in 32-Bit-Prozesse einzufügen, und ein 64-Bit-Anwendungsaufruf SetWindowsHookEx, um eine 64-Bit-DLL in 64-Bit-Prozesse einzufügen. Die 32-Bit- und 64-Bit-DLLs müssen unterschiedliche Namen haben.

Da Hooks im Kontext einer Anwendung ausgeführt werden, müssen sie mit der "Bitness" 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). Bei einem 64-Bit-Prozess werden die Threads weiterhin als "hooked" gekennzeichnet. Da jedoch eine 32-Bit-Anwendung den Hookcode ausführen muss, führt das System den Hook im Kontext der Hooking-App aus; speziell für den Thread, der SetWindowsHookExaufgerufen hat. Dies bedeutet, dass die Hooking-Anwendung weiterhin Nachrichten pumpt oder die normale Funktion der 64-Bit-Prozesse blockiert.

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 Hooking-Anwendung verwenden.

Um alle Anwendungen auf dem Desktop einer 64-Bit-Windows-Installation zu verbinden, installieren Sie einen globalen 32-Bit-Hook und einen globalen 64-Bit-Hook, die jeweils aus den entsprechenden Prozessen stammen, und achten Sie darauf, nachrichten in der Hooking-Anwendung zu pumpen, um zu verhindern, dass normale Funktionen blockiert werden. Wenn Sie bereits über eine globale 32-Bit-Hooking-Anwendung verfügen und nicht im Kontext jeder Anwendung ausgeführt werden müssen, müssen Sie möglicherweise keine 64-Bit-Version erstellen.

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

Das Aufrufen der CallNextHookEx-Funktion Funktion zum Verketten mit der nächsten Hook-Prozedur ist optional, wird jedoch dringend empfohlen; andernfalls erhalten andere Anwendungen, die Hooks installiert haben, keine Hook-Benachrichtigungen und verhalten sich möglicherweise falsch als Ergebnis. Rufen Sie CallNextHookEx auf, es sei denn, Sie müssen unbedingt verhindern, dass die Benachrichtigung von anderen Anwendungen angezeigt wird.

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

Der Umfang eines Hooks hängt vom Hakentyp ab. Einige Hooks können nur mit globaler Reichweite festgelegt werden; andere können auch nur für einen bestimmten Thread festgelegt werden, wie in der folgenden Tabelle dargestellt.

Haken	Umfang
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

Bei einem angegebenen Hook-Typ werden Thread-Hooks zuerst aufgerufen und dann globale Hooks. Beachten Sie, dass die WH_MOUSE, WH_KEYBOARD, WH_JOURNAL*, WH_SHELL und Low-Level-Hooks für den Thread aufgerufen werden können, der den Hook installiert hat, anstatt den Thread zu verarbeiten. Für diese Hooks ist es möglich, dass sowohl die 32-Bit- als auch die 64-Bit-Hooks aufgerufen werden, wenn ein 32-Bit-Hook vor einem 64-Bit-Hook in der Hakenkette liegt.

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 Hook-Funktionen müssen sich in Bibliotheken befinden. Globale Hooks sollten auf spezielle Anwendungen beschränkt oder während des Anwendungsdebuggings als Entwicklungshilfe verwendet werden. Bibliotheken, die keinen Hook mehr benötigen, sollten das Hook-Verfahren entfernen.

Entwicklung von Windows Store-Apps Wenn dwThreadId null ist, werden Windows-Hook-DLLs für die Windows Store-App-Prozesse und den Windows-Runtime-Brokerprozess nicht geladen, es sei denn, sie werden von uiAccess-Prozessen (Barrierefreiheitstools) installiert. Die Benachrichtigung wird im Thread des Installers 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 eine Architekturkonflikt zwischen der Hook-DLL und dem Zielanwendungsprozess auftritt, z. B. wenn die Hook-DLL 32-Bit und der Anwendungsprozess 64-Bit ist.

Beispiele

Ein Beispiel finden Sie unter Installing and Release Hook Procedures.

Anmerkung

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

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-window-l1-1-0 (eingeführt in Windows 8)