SetWindowsHookExA, fonction (winuser.h)

Article
03/13/2024

Installe une procédure de hook définie par l’application dans une chaîne de raccordement. Vous devez installer 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 SetWindowsHookExA(
  [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 prendre les valeurs suivantes.

Valeur	Signification
WH_CALLWNDPROC 4	Installe une procédure de raccordement 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 hook CallWndProc .
WH_CALLWNDPROCRET 12	Installe une procédure de raccordement qui surveille les messages après leur traitement par la procédure de la fenêtre de destination. Pour plus d’informations, consultez la procédure de hook [fonction de rappel HOOKPROC](nc-winuser-hookproc.md).
WH_CBT 5	Installe une procédure de hook qui reçoit des notifications utiles à une application CBT. Pour plus d’informations, consultez la procédure de hook CBTProc .
WH_DEBUG 9	Installe une procédure de hook utile pour déboguer d’autres procédures de hook. Pour plus d’informations, consultez la procédure de hook DebugProc .
WH_FOREGROUNDIDLE 11	Installe une procédure de raccordement 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 hook ForegroundIdleProc .
WH_GETMESSAGE 3	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 hook GetMsgProc .
WH_JOURNALPLAYBACK 1	Warning Windows 11 et versions ultérieures : les API de hook de journalisation ne sont pas prises en charge. Nous vous recommandons d’utiliser l’API TextInput SendInput à 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 hook JournalPlaybackProc .
WH_JOURNALRECORD 0	Avertissement Windows 11 et versions ultérieures : les API de hook de journalisation ne sont pas prises en charge. Nous vous recommandons d’utiliser l’API TextInput SendInput à 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 enregistrer des macros. Pour plus d’informations, consultez la procédure de hook JournalRecordProc .
WH_KEYBOARD 2	Installe une procédure de raccordement qui surveille les messages de séquence de touches. Pour plus d’informations, consultez la procédure de raccordement KeyboardProc .
WH_KEYBOARD_LL 13	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](/windows/win32/winmsg/lowlevelkeyboardproc).
WH_MOUSE 7	Installe une procédure de raccordement qui surveille les messages de la souris. Pour plus d’informations, consultez la procédure de hook MouseProc .
WH_MOUSE_LL 14	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 de hook LowLevelMouseProc .
WH_MSGFILTER -1	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 .
WH_SHELL 10	Installe une procédure de raccordement qui reçoit des notifications utiles aux applications shell. Pour plus d’informations, consultez la procédure de raccordement ShellProc .
WH_SYSMSGFILTER 6	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 hook 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 de la DLL contenant la procédure de raccordement pointée par 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 actuel et si la procédure de raccordement 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 raccordement 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 raccordement.

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 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 « crochetés ». 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 ; 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 avez déjà une application de raccordement global 32 bits et qu’elle n’a pas besoin de s’exécuter 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 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 à chaîner à 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 peuvent se comporter incorrectement en conséquence. Vous devez appeler CallNextHookEx , sauf si vous avez absolument besoin d’empêcher la notification d’être vue par d’autres applications.

Avant de se 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 crochet. Certains crochets ne peuvent être définis qu’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 d’abord appelés, 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 traitant 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’un affecte toutes les applications du même bureau que le thread appelant. Toutes les fonctions de hook global 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 des applications. Les bibliothèques qui n’ont plus besoin d’un hook doivent supprimer sa procédure de hook.

Développement d’applications du Windows Store Si dwThreadId a la valeur 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 broker Windows Runtime, sauf s’ils sont installés par l’un ou l’autre des 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

Ce comportement est similaire à ce qui se produit lorsqu’il existe une incompatibilité d’architecture entre la DLL de hook et le processus d’application cible, par exemple, lorsque la DLL de hook est 32 bits et que le processus d’application est 64 bits.

Exemples

Pour obtenir un exemple, consultez Installation et libération des procédures de hook.

Notes

L’en-tête winuser.h définit SetWindowsHookEx comme un 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.

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)