Fonction SetWinEventHook (winuser.h)
Définit une fonction de hook d’événements pour une plage d’événements.
Syntaxe
HWINEVENTHOOK SetWinEventHook(
[in] DWORD eventMin,
[in] DWORD eventMax,
[in] HMODULE hmodWinEventProc,
[in] WINEVENTPROC pfnWinEventProc,
[in] DWORD idProcess,
[in] DWORD idThread,
[in] DWORD dwFlags
);
Paramètres
[in] eventMin
Type : UINT
Spécifie la constante d’événement pour la valeur d’événement la plus faible dans la plage d’événements gérés par la fonction hook. Ce paramètre peut être défini sur EVENT_MIN pour indiquer la valeur d’événement la plus faible possible.
[in] eventMax
Type : UINT
Spécifie la constante d’événement pour la valeur d’événement la plus élevée dans la plage d’événements gérés par la fonction hook. Ce paramètre peut être défini sur EVENT_MAX pour indiquer la valeur d’événement la plus élevée possible.
[in] hmodWinEventProc
Type : HMODULE
Gérez la DLL qui contient la fonction hook au niveau de lpfnWinEventProc, si l’indicateur WINEVENT_INCONTEXT est spécifié dans le paramètre dwFlags . Si la fonction de hook ne se trouve pas dans une DLL ou si l’indicateur WINEVENT_OUTOFCONTEXT est spécifié, ce paramètre a la valeur NULL.
[in] pfnWinEventProc
Type : WINEVENTPROC
Pointeur vers la fonction de hook d’événement. Pour plus d’informations sur cette fonction, consultez WinEventProc.
[in] idProcess
Type : DWORD
Spécifie l’ID du processus à partir duquel la fonction de hook reçoit des événements. Spécifiez zéro (0) pour recevoir les événements de tous les processus sur le bureau actuel.
[in] idThread
Type : DWORD
Spécifie l’ID du thread à partir duquel la fonction de hook reçoit des événements. Si ce paramètre est égal à zéro, la fonction de hook est associée à tous les threads existants sur le bureau actuel.
[in] dwFlags
Type : UINT
Valeurs d’indicateur qui spécifient l’emplacement de la fonction de crochet et des événements à ignorer. Les indicateurs suivants sont valides :
| Valeur | Signification |
|---|---|
|
La DLL qui contient la fonction de rappel est mappée dans l’espace d’adressage du processus qui génère l’événement. Avec cet indicateur, le système envoie des notifications d’événements à la fonction de rappel au fur et à mesure qu’elles se produisent. La fonction de hook doit se trouver dans une DLL lorsque cet indicateur est spécifié. Cet indicateur n’a aucun effet lorsque le processus appelant et le processus de génération ne sont pas des processus 32 bits ou 64 bits, ou lorsque le processus de génération est une application console. Pour plus d’informations, consultez Fonctions de crochet en contexte. |
|
La fonction de rappel n’est pas mappée dans l’espace d’adressage du processus qui génère l’événement. Étant donné que la fonction de hook est appelée au-delà des limites du processus, le système doit mettre en file d’attente les événements. Bien que cette méthode soit asynchrone, les événements sont garantis dans l’ordre séquentiel. Pour plus d’informations, consultez Fonctions de crochet hors contexte. |
|
Empêche cette instance du hook de recevoir les événements générés par les threads de ce processus. Cet indicateur n’empêche pas les threads de générer des événements. |
|
Empêche cette instance du hook de recevoir les événements générés par le thread qui inscrit ce hook. |
Les combinaisons d’indicateurs suivantes sont valides :
- WINEVENT_INCONTEXT | WINEVENT_SKIPOWNPROCESS
- WINEVENT_INCONTEXT | WINEVENT_SKIPOWNTHREAD
- WINEVENT_OUTOFCONTEXT | WINEVENT_SKIPOWNPROCESS
- WINEVENT_OUTOFCONTEXT | WINEVENT_SKIPOWNTHREAD
Pour plus d’informations sur le développement d’applications du Windows Store, consultez la section Remarques.
Valeur retournée
Type : HWINEVENTHOOK
En cas de réussite, retourne une valeur HWINEVENTHOOK qui identifie ce instance de hook d’événement. Les applications enregistrent cette valeur de retour pour l’utiliser avec la fonction UnhookWinEvent .
En cas d’échec, retourne zéro.
Remarques
Cette fonction permet aux clients de spécifier les processus et les threads qui les intéressent.
Si le paramètre idProcess est différent de zéro et si idThread est égal à zéro, la fonction de hook reçoit les événements spécifiés de tous les threads de ce processus. Si le paramètre idProcess est égal à zéro et qu’idThread est différent de zéro, la fonction de hook reçoit les événements spécifiés uniquement à partir du thread spécifié par idThread. Si les deux sont zéro, la fonction de hook reçoit les événements spécifiés de tous les threads et processus.
Les clients peuvent appeler SetWinEventHook plusieurs fois s’ils souhaitent inscrire des fonctions de hook supplémentaires ou écouter des événements supplémentaires.
Le thread client qui appelle SetWinEventHook doit avoir une boucle de message pour recevoir des événements.
Lorsque vous utilisez SetWinEventHook pour définir un rappel dans le code managé, vous devez utiliser la structure GCHandle pour éviter les exceptions. Cela indique au garbage collector de ne pas déplacer le rappel.
Pour les événements hors contexte, l’événement est fourni sur le thread qui a appelé SetWinEventHook. Dans certains cas, même si vous demandez WINEVENT_INCONTEXT événements, les événements sont toujours fournis hors contexte. Ces scénarios incluent des événements provenant des fenêtres de console et des événements de processus qui ont une profondeur de bits différente (64 bits par rapport à 32 bits) de celle de l’appelant.
Pendant qu’une fonction de hook traite un événement, d’autres événements peuvent être déclenchés, ce qui peut entraîner la réentrée de la fonction de hook avant la fin du traitement de l’événement d’origine. Le problème avec la réentrance dans les fonctions de hook est que les événements sont terminés hors séquence, sauf si la fonction de crochet gère cette situation. Pour plus d’informations, consultez Protection contre la réentrance.
Développement d’applications du Windows Store Si dwFlags est WINEVENT_INCONTEXT AND (idProcess = 0 | idThread = 0), les DLL de hook de fenêtre ne sont pas chargées en cours de traitement pour les processus d’application du Windows Store et le processus broker Windows Runtime, sauf s’ils sont installés par des processus UIAccess (outils d’accessibilité). La notification est remise sur le thread du programme d’installation.
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
L’exemple de code suivant montre comment une application cliente peut écouter les événements de début et de fin de menu. Par souci de simplicité, le gestionnaire d’événements envoie simplement des informations à la sortie standard.
// Global variable.
HWINEVENTHOOK g_hook;
// Initializes COM and sets up the event hook.
//
void InitializeMSAA()
{
CoInitialize(NULL);
g_hook = SetWinEventHook(
EVENT_SYSTEM_MENUSTART, EVENT_SYSTEM_MENUEND, // Range of events (4 to 5).
NULL, // Handle to DLL.
HandleWinEvent, // The callback.
0, 0, // Process and thread IDs of interest (0 = all)
WINEVENT_OUTOFCONTEXT | WINEVENT_SKIPOWNPROCESS); // Flags.
}
// Unhooks the event and shuts down COM.
//
void ShutdownMSAA()
{
UnhookWinEvent(g_hook);
CoUninitialize();
}
// Callback function that handles events.
//
void CALLBACK HandleWinEvent(HWINEVENTHOOK hook, DWORD event, HWND hwnd,
LONG idObject, LONG idChild,
DWORD dwEventThread, DWORD dwmsEventTime)
{
IAccessible* pAcc = NULL;
VARIANT varChild;
HRESULT hr = AccessibleObjectFromEvent(hwnd, idObject, idChild, &pAcc, &varChild);
if ((hr == S_OK) && (pAcc != NULL))
{
BSTR bstrName;
pAcc->get_accName(varChild, &bstrName);
if (event == EVENT_SYSTEM_MENUSTART)
{
printf("Begin: ");
}
else if (event == EVENT_SYSTEM_MENUEND)
{
printf("End: ");
}
printf("%S\n", bstrName);
SysFreeString(bstrName);
pAcc->Release();
}
}
Configuration requise
| Condition requise | Valeur |
|---|---|
| Client minimal pris en charge | Windows 2000 Professionnel [applications de bureau uniquement] |
| Serveur minimal pris en charge | Windows Server 2003 [applications de bureau uniquement] |
| Plateforme cible | Windows |
| En-tête | winuser.h (inclure Windows.h) |
| Bibliothèque | User32.lib |
| DLL | User32.dll |
| Composant redistribuable | Active Accessibility 1.3 RDK sur Windows NT 4.0 avec SP6 et versions ultérieures et Windows 95 |