SetWindowsHookExA-Funktion (winuser.h)
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 |
|---|---|
|
Installiert eine Hookprozedur, die Nachrichten überwacht, bevor das System sie an die Zielfensterprozedur sendet. Weitere Informationen finden Sie in der Hookprozedur CallWndProc . |
|
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). |
|
Installiert eine Hookprozedur, die Benachrichtigungen empfängt, die für eine CBT-Anwendung nützlich sind. Weitere Informationen finden Sie in der CBTProc-Hookprozedur . |
|
Installiert eine Hookprozedur, die zum Debuggen anderer Hookprozeduren nützlich ist. Weitere Informationen finden Sie in der DebugProc-Hookprozedur . |
|
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 . |
|
Installiert eine Hookprozedur, die Nachrichten überwacht, die an eine Nachrichtenwarteschlange gesendet werden. Weitere Informationen finden Sie in der Hookprozedur GetMsgProc . |
|
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 . |
|
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 . |
|
Installiert eine Hookprozedur, die Tastatureingabemeldungen überwacht. Weitere Informationen finden Sie unter KeyboardProc-Hookprozedur . |
|
Installiert eine Hookprozedur, die Tastatureingabeereignisse auf niedriger Ebene überwacht. Weitere Informationen finden Sie in der Hookprozedur [LowLevelKeyboardProc](/windows/win32/winmsg/lowlevelkeyboardproc). |
|
Installiert eine Hookprozedur, die Mausnachrichten überwacht. Weitere Informationen finden Sie unter MouseProc-Hookprozedur . |
|
Installiert eine Hookprozedur, die Mauseingabeereignisse auf niedriger Ebene überwacht. Weitere Informationen finden Sie in der Hookprozedur LowLevelMouseProc . |
|
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 . |
|
Installiert eine Hookprozedur, die Benachrichtigungen empfängt, die für Shellanwendungen nützlich sind. Weitere Informationen finden Sie in der ShellProc-Hookprozedur . |
|
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, ist es erforderlich, dass eine 32-Bit-Anwendung SetWindowsHookEx aufruft, um 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 "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 (es gelten die üblichen Sicherheitsgrenzen). 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 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 Hookinganwendung verwenden.
Wenn Sie alle Anwendungen auf dem Desktop einer 64-Bit-Windows-Installation einbinden möchten, installieren Sie einen globalen 32-Bit-Hook und einen globalen 64-Bit-Hook aus entsprechenden Prozessen, und stellen Sie sicher, dass Sie weiterhin Nachrichten in der Hookinganwendung pumpen, um die normale Funktion zu vermeiden. 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 und der dwThreadId-Parameter null ist oder den Bezeichner eines von einem anderen Prozess erstellten Threads angibt.
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 globalem 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 Threadhaken und dann globale Hooks aufgerufen. 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, und nicht für den Thread, der den Hook verarbeitet. Bei diesen 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-Haken in der Hakenkette 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 Windows-Hook-DLLs nicht prozessintern für die Windows Store-App-Prozesse und den Windows-Runtime Brokerprozess geladen, es sei denn, sie werden von beiden UIAccess-Prozessen (Barrierefreiheitstools) installiert. Die Benachrichtigung wird im Thread des Installers für die folgenden Hooks übermittelt:
- WH_JOURNALPLAYBACK
- WH_JOURNALRECORD
- WH_KEYBOARD
- WH_KEYBOARD_LL
- WH_MOUSE
- WH_MOUSE_LL
Beispiele
Ein Beispiel finden Sie unter Installieren und Freigeben von Hookprozeduren.
Hinweis
Der winuser.h-Header definiert SetWindowsHookEx 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 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-window-l1-1-0 (eingeführt in Windows 8) |
Weitere Informationen
Konzept