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
WINEVENT_INCONTEXT
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.
WINEVENT_OUTOFCONTEXT
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.
WINEVENT_SKIPOWNPROCESS
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.
WINEVENT_SKIPOWNTHREAD
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
En outre, les applications clientes peuvent spécifier WINEVENT_INCONTEXT ou WINEVENT_OUTOFCONTEXT seules.

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

Voir aussi

Inscription d’une fonction Hook

UnhookWinEvent

WinEventProc