SetWindowsHookExW, fonction (winuser.h)
Installe une procédure de hook définie par l’application dans une chaîne de crochets. Vous installez une procédure de raccordement pour surveiller le système pour certains types d’événements. Ces événements sont associés à un thread spécifique ou à tous les threads du même bureau que le thread appelant.
Syntaxe
HHOOK SetWindowsHookExW(
[in] int idHook,
[in] HOOKPROC lpfn,
[in] HINSTANCE hmod,
[in] DWORD dwThreadId
);
Paramètres
[in] idHook
Type : int
Type de procédure de raccordement à installer. Ce paramètre peut être l’une des valeurs suivantes.
| Valeur | Signification |
|---|---|
|
Installe une procédure de hook qui surveille les messages avant que le système les envoie à la procédure de fenêtre de destination. Pour plus d’informations, consultez la procédure de raccordement callWndProc |
|
Installe une procédure de hook qui surveille les messages une fois qu’ils ont été traités par la procédure de fenêtre de destination. Pour plus d’informations, consultez la fonction de rappel HOOKPROC procédure de raccordement. |
|
Installe une procédure de hook qui reçoit des notifications utiles à une application CBT. Pour plus d’informations, consultez la procédure de raccordement CBTProc. |
|
Installe une procédure de hook utile pour le débogage d’autres procédures de hook. Pour plus d’informations, consultez la procédure de raccordement DebugProc. |
|
Installe une procédure de hook qui sera appelée lorsque le thread de premier plan de l’application est sur le point de devenir inactif. Ce hook est utile pour effectuer des tâches de faible priorité pendant le temps d’inactivité. Pour plus d’informations, consultez la procédure de raccordement ForegroundIdleProc. |
|
Installe une procédure de raccordement qui surveille les messages publiés dans une file d’attente de messages. Pour plus d’informations, consultez la procédure de raccordement GetMsgProc |
|
Avertissement Les API Hooks de journalisation ne sont pas prises en charge à partir de Windows 11 et seront supprimées dans une prochaine version. En raison de cela, nous vous recommandons vivement d’appeler l’API SendInput TextInput à la place. Installe une procédure de hook qui publie des messages précédemment enregistrés par une procédure de hook WH_JOURNALRECORD. Pour plus d’informations, consultez la procédure de raccordement JournalPlaybackProc. |
|
Avertissement Les API Hooks de journalisation ne sont pas prises en charge à partir de Windows 11 et seront supprimées dans une prochaine version. En raison de cela, nous vous recommandons vivement d’appeler l’API SendInput TextInput à la place. Installe une procédure de raccordement qui enregistre les messages d’entrée publiés dans la file d’attente des messages système. Ce hook est utile pour l’enregistrement des macros. Pour plus d’informations, consultez la procédure de raccordement JournalRecordProc. |
|
Installe une procédure de raccordement qui surveille les messages de séquence de touches. Pour plus d’informations, consultez la procédure de hook |
|
Installe une procédure de raccordement qui surveille les événements d’entrée clavier de bas niveau. Pour plus d’informations, consultez la procédure de raccordement LowLevelKeyboardProc. |
|
Installe une procédure de raccordement qui surveille les messages de la souris. Pour plus d’informations, consultez la procédure de raccordement MouseProc. |
|
Installe une procédure de raccordement qui surveille les événements d’entrée de souris de bas niveau. Pour plus d’informations, consultez la procédure LowLevelMouseProc hook. |
|
Installe une procédure de raccordement qui surveille les messages générés à la suite d’un événement d’entrée dans une boîte de dialogue, une boîte de message, un menu ou une barre de défilement. Pour plus d’informations, consultez la procédure de hook MessageProc. |
|
Installe une procédure de hook qui reçoit des notifications utiles pour les applications shell. Pour plus d’informations, consultez la procédure de raccordement ShellProc. |
|
Installe une procédure de raccordement qui surveille les messages générés à la suite d’un événement d’entrée dans une boîte de dialogue, une boîte de message, un menu ou une barre de défilement. La procédure de raccordement surveille ces messages pour toutes les applications du même bureau que le thread appelant. Pour plus d’informations, consultez la procédure de raccordement SysMsgProc. |
[in] lpfn
Type : HOOKPROC
Pointeur vers la procédure de raccordement. Si le paramètre dwThreadId est égal à zéro ou spécifie l’identificateur d’un thread créé par un autre processus, le paramètre lpfn doit pointer vers une procédure de raccordement dans une DLL. Sinon, lpfn peut pointer vers une procédure de raccordement dans le code associé au processus actuel.
[in] hmod
Type : HINSTANCE
Handle vers la DLL contenant la procédure de hook pointée par le paramètre lpfn. Le paramètre hMod doit être défini sur null si le paramètre dwThreadId spécifie un thread créé par le processus actuel et si la procédure de hook se trouve dans le code associé au processus actuel.
[in] dwThreadId
Type : DWORD
Identificateur du thread auquel la procédure de raccordement doit être associée. Pour les applications de bureau, si ce paramètre est égal à zéro, la procédure de hook est associée à tous les threads existants s’exécutant dans le même bureau que le thread appelant. Pour les applications du Windows Store, consultez la section Remarques.
Valeur de retour
Type : HHOOK
Si la fonction réussit, la valeur de retour est le handle de la procédure de raccordement.
Si la fonction échoue, la valeur de retour est NULL . Pour obtenir des informations d’erreur étendues, appelez GetLastError.
Remarques
SetWindowsHookEx pouvez être utilisé pour injecter une DLL dans un autre processus. Une DLL 32 bits ne peut pas être injectée dans un processus 64 bits, et une DLL 64 bits ne peut pas être injectée dans un processus 32 bits. Si une application nécessite l’utilisation de hooks dans d’autres processus, il est nécessaire qu’un appel d’application 32 bits SetWindowsHookEx injecter une DLL 32 bits dans des processus 32 bits et un appel d’application 64 bits SetWindowsHookEx pour injecter une DLL 64 bits dans des processus 64 bits. Les DLL 32 bits et 64 bits doivent avoir des noms différents.
Étant donné que les hooks s’exécutent dans le contexte d’une application, ils doivent correspondre au « bitness » de l’application. Si une application 32 bits installe un hook global sur Windows 64 bits, le hook 32 bits est injecté dans chaque processus 32 bits (les limites de sécurité habituelles s’appliquent). Dans un processus 64 bits, les threads sont toujours marqués comme « hooked ». Toutefois, étant donné qu’une application 32 bits doit exécuter le code de hook, le système exécute le hook dans le contexte de l’application de raccordement ; spécifiquement, sur le thread qui a appelé SetWindowsHookEx. Cela signifie que l’application de raccordement doit continuer à pomper les messages ou peut bloquer le fonctionnement normal des processus 64 bits.
Si une application 64 bits installe un hook global sur Windows 64 bits, le hook 64 bits est injecté dans chaque processus 64 bits, tandis que tous les processus 32 bits utilisent un rappel à l’application de raccordement.
Pour raccorder toutes les applications sur le bureau d’une installation Windows 64 bits, installez un hook global 32 bits et un hook global 64 bits, chacun à partir de processus appropriés et veillez à continuer à pomper les messages dans l’application de raccordement pour éviter de bloquer le fonctionnement normal. Si vous disposez déjà d’une application de raccordement global 32 bits et qu’elle n’a pas besoin d’être exécutée dans le contexte de chaque application, vous n’avez peut-être pas besoin de créer une version 64 bits.
Une erreur peut se produire si le paramètre hMod
L’appel de la fonction CallNextHookEx fonction pour chaîner à la procédure de raccordement suivante est facultative, mais il est fortement recommandé ; sinon, les autres applications qui ont installé des hooks ne recevront pas de notifications de hook et peuvent se comporter de manière incorrecte en conséquence. Vous devez appeler CallNextHookEx, sauf si vous devez absolument empêcher la notification d’être vue par d’autres applications.
Dans les applications .NET, vous devez vous assurer que le rappel n’est pas déplacé par le garbage collector (sinon, votre application se bloque avec un ExecutionEngineException). Pour ce faire, le rappel est une méthode statique de votre classe.
Avant de terminer, une application doit appeler la fonction UnhookWindowsHookEx fonction pour libérer les ressources système associées au hook.
L’étendue d’un crochet dépend du type de crochet. Certains crochets ne peuvent être définis qu’avec une étendue globale ; d’autres peuvent également être définis pour un thread spécifique, comme indiqué dans le tableau suivant.
| Crochet | Portée |
|---|---|
| WH_CALLWNDPROC | Thread ou global |
| WH_CALLWNDPROCRET | Thread ou global |
| WH_CBT | Thread ou global |
| WH_DEBUG | Thread ou global |
| WH_FOREGROUNDIDLE | Thread ou global |
| WH_GETMESSAGE | Thread ou global |
| WH_JOURNALPLAYBACK | Global uniquement |
| WH_JOURNALRECORD | Global uniquement |
| WH_KEYBOARD | Thread ou global |
| WH_KEYBOARD_LL | Global uniquement |
| WH_MOUSE | Thread ou global |
| WH_MOUSE_LL | Global uniquement |
| WH_MSGFILTER | Thread ou global |
| WH_SHELL | Thread ou global |
| WH_SYSMSGFILTER | Global uniquement |
Pour un type de hook spécifié, les crochets de thread sont appelés en premier, puis les crochets globaux. N’oubliez pas que les WH_MOUSE, les WH_KEYBOARD, les WH_JOURNAL*, les WH_SHELL et les crochets de bas niveau peuvent être appelés sur le thread qui a installé le crochet plutôt que le thread qui traite le hook. Pour ces crochets, il est possible que les crochets 32 bits et 64 bits soient appelés si un crochet 32 bits est à l’avance d’un crochet 64 bits dans la chaîne de crochet.
Les hooks globaux sont une ressource partagée et l’installation d’une ressource affecte toutes les applications du même bureau que le thread appelant. Toutes les fonctions de hook globales doivent se trouver dans des bibliothèques. Les hooks globaux doivent être limités à des applications à usage spécial ou à utiliser comme aide au développement pendant le débogage des applications. Les bibliothèques qui n’ont plus besoin d’un hook doivent supprimer sa procédure de raccordement.
applications du Windows Store : Si dwThreadId est égal à zéro, les DLL de hook de fenêtre ne sont pas chargées en cours pour les processus d’application du Windows Store et le processus du répartiteur Windows Runtime, sauf s’ils sont installés par les processus UIAccess (outils d’accessibilité). La notification est remise sur le thread du programme d’installation pour ces hooks :
- WH_JOURNALPLAYBACK
- WH_JOURNALRECORD
- WH_KEYBOARD
- WH_KEYBOARD_LL
- WH_MOUSE
- WH_MOUSE_LL
Exemples
Pour obtenir un exemple, consultez procédures d’installation et de libération de hooks.
Note
L’en-tête winuser.h définit SetWindowsHookEx comme alias qui sélectionne automatiquement la version ANSI ou Unicode de cette fonction en fonction de la définition de la constante de préprocesseur UNICODE. Le mélange de l’utilisation de l’alias neutre en encodage avec du code qui n’est pas neutre en encodage peut entraîner des incompatibilités qui entraînent des erreurs de compilation ou d’exécution. Pour plus d’informations, consultez Conventions pour les prototypes de fonction.
Exigences
| Exigence | Valeur |
|---|---|
| client minimum pris en charge | Windows 2000 Professionnel [applications de bureau uniquement] |
| serveur minimum pris en charge | Windows 2000 Server [applications de bureau uniquement] |
| plateforme cible | Windows |
| d’en-tête | winuser.h (include Windows.h) |
| bibliothèque | User32.lib |
| DLL | User32.dll |
| ensemble d’API | ext-ms-win-ntuser-window-l1-1-0 (introduit dans Windows 8) |
Voir aussi
conceptuelle