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 |
|---|---|
|
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. |
|
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. |
|
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. |
|
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
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 |