Freigeben über


SetWinEventHook-Funktion (winuser.h)

Legt eine Ereignishookfunktion für einen Bereich von Ereignissen fest.

Syntax

HWINEVENTHOOK SetWinEventHook(
  [in] DWORD        eventMin,
  [in] DWORD        eventMax,
  [in] HMODULE      hmodWinEventProc,
  [in] WINEVENTPROC pfnWinEventProc,
  [in] DWORD        idProcess,
  [in] DWORD        idThread,
  [in] DWORD        dwFlags
);

Parameter

[in] eventMin

Typ: UINT

Gibt die Ereigniskonstante für den niedrigsten Ereigniswert im Bereich von Ereignissen an, die von der Hookfunktion behandelt werden. Dieser Parameter kann auf EVENT_MIN festgelegt werden, um den niedrigsten möglichen Ereigniswert anzugeben.

[in] eventMax

Typ: UINT

Gibt die Ereigniskonstante für den höchsten Ereigniswert im Bereich von Ereignissen an, die von der Hookfunktion behandelt werden. Dieser Parameter kann auf EVENT_MAX festgelegt werden, um den höchstmöglichen Ereigniswert anzugeben.

[in] hmodWinEventProc

Typ: HMODULE

Handle mit der DLL, die die Hookfunktion in lpfnWinEventProc enthält, wenn das WINEVENT_INCONTEXT-Flag im dwFlags-Parameter angegeben ist. Wenn sich die Hookfunktion nicht in einer DLL befindet oder das flag WINEVENT_OUTOFCONTEXT angegeben ist, ist dieser Parameter NULL.

[in] pfnWinEventProc

Typ: WINEVENTPROC

Zeiger auf die Ereignishookfunktion. Weitere Informationen zu dieser Funktion finden Sie unter WinEventProc.

[in] idProcess

Typ: DWORD

Gibt die ID des Prozesses an, von dem die Hookfunktion Ereignisse empfängt. Geben Sie null (0) an, um Ereignisse von allen Prozessen auf dem aktuellen Desktop zu empfangen.

[in] idThread

Typ: DWORD

Gibt die ID des Threads an, von dem die Hookfunktion Ereignisse empfängt. Wenn dieser Parameter null ist, wird die Hookfunktion allen vorhandenen Threads auf dem aktuellen Desktop zugeordnet.

[in] dwFlags

Typ: UINT

Flagwerte, die den Speicherort der Hookfunktion und der zu überspringenden Ereignisse angeben. Die folgenden Flags sind gültig:

Wert Bedeutung
WINEVENT_INCONTEXT
Die DLL, die die Rückruffunktion enthält, wird dem Adressraum des Prozesses zugeordnet, der das Ereignis generiert. Mit diesem Flag sendet das System ereignisbenachrichtigungen an die Rückruffunktion, sobald sie auftreten. Die Hookfunktion muss sich in einer DLL befinden, wenn dieses Flag angegeben wird. Dieses Flag hat keine Auswirkung, wenn sowohl der aufrufende Prozess als auch der generierende Prozess keine 32-Bit- oder 64-Bit-Prozesse sind oder wenn der generierende Prozess eine Konsolenanwendung ist. Weitere Informationen finden Sie unter In-Context Hook Functions.
WINEVENT_OUTOFCONTEXT
Die Rückruffunktion ist nicht dem Adressraum des Prozesses zugeordnet, der das Ereignis generiert. Da die Hookfunktion über Prozessgrenzen hinweg aufgerufen wird, muss das System Ereignisse in die Warteschlange stellen. Obwohl diese Methode asynchron ist, werden Ereignisse garantiert in sequenzieller Reihenfolge ausgeführt. Weitere Informationen finden Sie unter Out-of-Context Hook Functions.
WINEVENT_SKIPOWNPROCESS
Verhindert, dass dieser instance des Hooks die Ereignisse empfängt, die von Threads in diesem Prozess generiert werden. Dieses Flag verhindert nicht, dass Threads Ereignisse generieren.
WINEVENT_SKIPOWNTHREAD
Verhindert, dass dieser instance des Hooks die Ereignisse empfängt, die von dem Thread generiert werden, der diesen Hook registriert.
 

Die folgenden Flagkombinationen sind gültig:

  • WINEVENT_INCONTEXT | WINEVENT_SKIPOWNPROCESS
  • WINEVENT_INCONTEXT | WINEVENT_SKIPOWNTHREAD
  • WINEVENT_OUTOFCONTEXT | WINEVENT_SKIPOWNPROCESS
  • WINEVENT_OUTOFCONTEXT | WINEVENT_SKIPOWNTHREAD
Darüber hinaus können Clientanwendungen WINEVENT_INCONTEXT oder WINEVENT_OUTOFCONTEXT allein angeben.

Informationen zur Entwicklung von Windows Store-Apps finden Sie im Abschnitt Hinweise.

Rückgabewert

Typ: HWINEVENTHOOK

Gibt bei erfolgreicher Ausführung einen HWINEVENTHOOK-Wert zurück, der diesen Ereignishook instance identifiziert. Anwendungen speichern diesen Rückgabewert, um ihn mit der UnhookWinEvent-Funktion zu verwenden.

Wenn der Fehler nicht erfolgreich ist, wird 0 (null) zurückgegeben.

Hinweise

Mit dieser Funktion können Clients angeben, an welchen Prozessen und Threads sie interessiert sind.

Wenn der Parameter idProcess ungleich null und idThread null ist, empfängt die Hookfunktion die angegebenen Ereignisse von allen Threads in diesem Prozess. Wenn der idProcess-Parameter null und idThread ungleich null ist, empfängt die Hookfunktion die angegebenen Ereignisse nur von dem von idThread angegebenen Thread. Wenn beide null sind, empfängt die Hookfunktion die angegebenen Ereignisse von allen Threads und Prozessen.

Clients können SetWinEventHook mehrmals aufrufen, wenn sie zusätzliche Hookfunktionen registrieren oder auf zusätzliche Ereignisse lauschen möchten.

Der Clientthread, der SetWinEventHook aufruft , muss über eine Nachrichtenschleife verfügen, um Ereignisse empfangen zu können.

Wenn Sie SetWinEventHook verwenden, um einen Rückruf in verwaltetem Code festzulegen, sollten Sie die GCHandle-Struktur verwenden, um Ausnahmen zu vermeiden. Dadurch wird der Garbage Collector aufgefordert, den Rückruf nicht zu verschieben.

Für Ereignisse außerhalb des Kontexts wird das Ereignis im selben Thread übermittelt, der SetWinEventHook aufgerufen hat. In einigen Situationen, auch wenn Sie WINEVENT_INCONTEXT Ereignisse anfordern, werden die Ereignisse weiterhin außerhalb des Kontexts übermittelt. Diese Szenarien umfassen Ereignisse von Konsolenfenstern und Ereignisse von Prozessen, die eine andere Bittiefe (64 Bit gegenüber 32 Bit) als der Aufrufer haben.

Während eine Hookfunktion ein Ereignis verarbeitet, können zusätzliche Ereignisse ausgelöst werden, was dazu führen kann, dass die Hookfunktion erneut eingibt, bevor die Verarbeitung für das ursprüngliche Ereignis abgeschlossen ist. Das Problem mit der Wiedereinbindung in Hookfunktionen besteht darin, dass Ereignisse außerhalb der Reihenfolge abgeschlossen werden, es sei denn, die Hookfunktion behandelt diese Situation. Weitere Informationen finden Sie unter Schutz vor Reentrancy.

Entwicklung von Windows Store-Apps Wenn dwFlags WINEVENT_INCONTEXT AND ist (idProcess = 0 | idThread = 0), werden Fenster-Hook-DLLs nicht in den Prozess für die Windows Store-App-Prozesse und den Windows-Runtime Brokerprozess geladen, es sei denn, sie werden von UIAccess-Prozessen (Barrierefreiheitstools) installiert. Die Benachrichtigung wird im Thread des Installationsprogramms übermittelt.

Dieses Verhalten ähnelt dem, was passiert, wenn ein Architekturkonflikt zwischen der Hook-DLL und dem Zielanwendungsprozess besteht, z. B. wenn die Hook-DLL 32-Bit und der Anwendungsprozess 64-Bit ist.

Beispiele

Der folgende Beispielcode zeigt, wie eine Clientanwendung auf Menüstart- und Menüendeereignisse lauscht. Der Einfachheit halber sendet der Ereignishandler nur einige Informationen an die Standardausgabe.


// 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();
    }
}

Anforderungen

Anforderung Wert
Unterstützte Mindestversion (Client) Windows 2000 Professional [nur Desktop-Apps]
Unterstützte Mindestversion (Server) Windows Server 2003 [nur Desktop-Apps]
Zielplattform Windows
Kopfzeile winuser.h (windows.h einschließen)
Bibliothek User32.lib
DLL User32.dll
Verteilbare Komponente Active Accessibility 1.3 RDK unter Windows NT 4.0 mit SP6 und höher und Windows 95

Weitere Informationen

Registrieren einer Hook-Funktion

UnhookWinEvent

WinEventProc