SetWindowsHookExW, fonction (winuser.h)
Installe une procédure de hook définie par l’application dans une chaîne de crochet. Vous devez installer une procédure de hook 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 crochet à installer. Ce paramètre peut prendre les valeurs suivantes.
| Valeur | Signification |
|---|---|
|
Installe une procédure de hook qui surveille les messages avant que le système ne les envoie à la procédure de la fenêtre de destination. Pour plus d’informations, consultez la procédure de crochet CallWndProc . |
|
Installe une procédure de hook qui surveille les messages une fois qu’ils ont été traités par la procédure de la fenêtre de destination. Pour plus d’informations, consultez la procédure hook de la fonction de rappel HOOKPROC . |
|
Installe une procédure de hook qui reçoit des notifications utiles à une application CBT. Pour plus d’informations, consultez la procédure de crochet 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 crochet 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 crochet est utile pour effectuer des tâches de faible priorité pendant le temps d’inactivité. Pour plus d’informations, consultez la procédure de crochet ForegroundIdleProc . |
|
Installe une procédure de hook qui surveille les messages publiés dans une file d’attente de messages. Pour plus d’informations, consultez la procédure de crochet GetMsgProc . |
|
Warning Les API de crochets de journalisation ne sont pas prises en charge à partir de Windows 11 et seront supprimées dans une version ultérieure. Pour cette raison, 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 crochet JournalPlaybackProc . |
|
Avertissement Les API de crochets de journalisation ne sont pas prises en charge à partir de Windows 11 et seront supprimées dans une version ultérieure. Pour cette raison, nous vous recommandons vivement d’appeler l’API SendInput TextInput à la place. Installe une procédure de hook qui enregistre les messages d’entrée publiés dans la file d’attente des messages système. Ce crochet est utile pour enregistrer des macros. Pour plus d’informations, consultez la procédure de crochet JournalRecordProc . |
|
Installe une procédure de crochet qui surveille les messages de frappe. Pour plus d’informations, consultez la procédure de crochet KeyboardProc . |
|
Installe une procédure de crochet qui surveille les événements d’entrée au clavier de bas niveau. Pour plus d’informations, consultez la procédure de crochet LowLevelKeyboardProc . |
|
Installe une procédure de crochet qui surveille les messages de la souris. Pour plus d’informations, consultez la procédure de crochet MouseProc . |
|
Installe une procédure de hook qui surveille les événements d’entrée de la souris de bas niveau. Pour plus d’informations, consultez la procédure de crochet LowLevelMouseProc . |
|
Installe une procédure de hook 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 crochet MessageProc . |
|
Installe une procédure de hook qui reçoit des notifications utiles aux applications shell. Pour plus d’informations, consultez la procédure de crochet ShellProc . |
|
Installe une procédure de hook 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 hook surveille ces messages pour toutes les applications du même bureau que le thread appelant. Pour plus d’informations, consultez la procédure de crochet SysMsgProc . |
[in] lpfn
Type : HOOKPROC
Pointeur vers la procédure de hook. 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 hook dans une DLL. Sinon, lpfn peut pointer vers une procédure de hook dans le code associé au processus en cours.
[in] hmod
Type : HINSTANCE
Handle de la DLL contenant la procédure de hook pointée vers le paramètre lpfn . Le paramètre hMod doit avoir la valeur NULL si le paramètre dwThreadId spécifie un thread créé par le processus en cours et si la procédure de hook se trouve dans le code associé au processus en cours.
[in] dwThreadId
Type : DWORD
Identificateur du thread auquel la procédure de hook 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 retournée
Type : HHOOK
Si la fonction réussit, la valeur de retour est le handle de la procédure de hook.
Si la fonction échoue, la valeur de retour est NULL. Pour obtenir des informations détaillées sur l’erreur, appelez GetLastError.
Remarques
SetWindowsHookEx peut ê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’une application 32 bits appelle SetWindowsHookEx pour injecter une DLL 32 bits dans des processus 32 bits, et qu’une application 64 bits appelle 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 à la « 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 raccordement, le système exécute le hook dans le contexte de l’application de raccordement ; plus précisément, 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 des 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 de s’exécuter dans chaque contexte d’application, vous n’aurez peut-être pas besoin de créer une version 64 bits.
Une erreur peut se produire si le paramètre hMod a la valeur NULL et si le paramètre dwThreadId est égal à zéro ou spécifie l’identificateur d’un thread créé par un autre processus.
L’appel de la fonction CallNextHookEx à la chaîne à la procédure de hook suivante est facultatif, mais il est fortement recommandé ; dans le cas contraire, d’autres applications qui ont installé des hooks ne recevront pas de notifications de hook et risquent de se comporter de manière incorrecte. Vous devez appeler CallNextHookEx , sauf si vous devez absolument empêcher la notification d’être visible par d’autres applications.
Avant de terminer, une application doit appeler la fonction UnhookWindowsHookEx pour libérer les ressources système associées au hook.
L’étendue d’un crochet dépend du type de hook. Certains crochets peuvent être définis uniquement avec une étendue globale ; d’autres peuvent également être définis uniquement pour un thread spécifique, comme indiqué dans le tableau suivant.
| Hook | Étendue |
|---|---|
| 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 hooks de thread sont appelés en premier, puis les hooks globaux. N’oubliez pas que les crochets WH_MOUSE, WH_KEYBOARD, WH_JOURNAL*, WH_SHELL et de bas niveau peuvent être appelés sur le thread qui a installé le crochet plutôt que sur le thread qui traite le crochet. Pour ces crochets, il est possible que les crochets 32 bits et 64 bits soient appelés si un crochet 32 bits est en avance sur 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 raccordement globales doivent se trouver dans des bibliothèques. Les hooks globaux doivent être limités aux applications à usage spécial ou à utiliser comme aide au développement pendant le débogage de l’application. Les bibliothèques qui n’ont plus besoin d’un hook doivent supprimer leur procédure de hook.
Applications du Windows Store : Si dwThreadId est égal à zéro, les DLL de raccordement de fenêtre ne sont pas chargées in-process pour les processus d’application du Windows Store et le processus broker Windows Runtime, sauf si elles sont installées 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 Installation et libération de procédures de hook.
Notes
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. La combinaison 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.
Configuration requise
| Condition requise | Valeur |
|---|---|
| Client minimal pris en charge | Windows 2000 Professionnel [applications de bureau uniquement] |
| Serveur minimal pris en charge | Windows 2000 Server [applications de bureau uniquement] |
| Plateforme cible | Windows |
| En-tête | winuser.h (inclure 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
Conceptuel