Funzione SetWinEventHook (winuser.h)
Imposta una funzione hook di eventi per un intervallo di eventi.
Sintassi
HWINEVENTHOOK SetWinEventHook(
[in] DWORD eventMin,
[in] DWORD eventMax,
[in] HMODULE hmodWinEventProc,
[in] WINEVENTPROC pfnWinEventProc,
[in] DWORD idProcess,
[in] DWORD idThread,
[in] DWORD dwFlags
);
Parametri
[in] eventMin
Tipo: UINT
Specifica la costante dell'evento per il valore dell'evento più basso nell'intervallo di eventi gestiti dalla funzione hook. Questo parametro può essere impostato su EVENT_MIN per indicare il valore di evento più basso possibile.
[in] eventMax
Tipo: UINT
Specifica la costante dell'evento per il valore di evento più alto nell'intervallo di eventi gestiti dalla funzione hook. Questo parametro può essere impostato su EVENT_MAX per indicare il valore di evento più alto possibile.
[in] hmodWinEventProc
Tipo: HMODULE
Gestire la DLL che contiene la funzione hook in lpfnWinEventProc, se il flag WINEVENT_INCONTEXT è specificato nel parametro dwFlags . Se la funzione hook non si trova in una DLL o se viene specificato il flag di WINEVENT_OUTOFCONTEXT, questo parametro è NULL.
[in] pfnWinEventProc
Tipo: WINEVENTPROC
Puntatore alla funzione hook dell'evento. Per altre informazioni su questa funzione, vedere WinEventProc.
[in] idProcess
Tipo: DWORD
Specifica l'ID del processo da cui la funzione hook riceve gli eventi. Specificare zero (0) per ricevere eventi da tutti i processi nel desktop corrente.
[in] idThread
Tipo: DWORD
Specifica l'ID del thread da cui la funzione hook riceve gli eventi. Se questo parametro è zero, la funzione hook viene associata a tutti i thread esistenti sul desktop corrente.
[in] dwFlags
Tipo: UINT
Contrassegnare i valori che specificano la posizione della funzione hook e degli eventi da ignorare. I flag seguenti sono validi:
| Valore | Significato |
|---|---|
|
La DLL che contiene la funzione di callback viene mappata nello spazio indirizzi del processo che genera l'evento. Con questo flag, il sistema invia notifiche degli eventi alla funzione di callback man mano che si verificano. Quando si specifica questo flag, la funzione hook deve trovarsi in una DLL. Questo flag non ha alcun effetto quando sia il processo chiamante che il processo di generazione non sono processi a 32 bit o a 64 bit o quando il processo di generazione è un'applicazione console. Per altre informazioni, vedere Funzioni hook nel contesto. |
|
La funzione di callback non viene mappata nello spazio indirizzi del processo che genera l'evento. Poiché la funzione hook viene chiamata attraverso i limiti del processo, il sistema deve accodare gli eventi. Anche se questo metodo è asincrono, gli eventi sono garantiti in ordine sequenziale. Per altre informazioni, vedere Funzioni hook out-of-context. |
|
Impedisce a questa istanza dell'hook di ricevere gli eventi generati dai thread in questo processo. Questo flag non impedisce ai thread di generare eventi. |
|
Impedisce a questa istanza dell'hook di ricevere gli eventi generati dal thread che registra questo hook. |
Le combinazioni di flag seguenti sono valide:
- WINEVENT_INCONTEXT | WINEVENT_SKIPOWNPROCESS
- WINEVENT_INCONTEXT | WINEVENT_SKIPOWNTHREAD
- WINEVENT_OUTOFCONTEXT | WINEVENT_SKIPOWNPROCESS
- WINEVENT_OUTOFCONTEXT | WINEVENT_SKIPOWNTHREAD
Per informazioni sullo sviluppo di app di Windows Store, vedere la sezione Osservazioni.
Valore restituito
Tipo: HWINEVENTHOOK
In caso di esito positivo, restituisce un valore HWINEVENTHOOK che identifica questa istanza dell'hook dell'evento. Le applicazioni salvano questo valore restituito per usarlo con la funzione UnhookWinEvent .
Se ha esito negativo, restituisce zero.
Commenti
Questa funzione consente ai client di specificare quali processi e thread sono interessati.
Se il parametro idProcess è diverso da zero e idThread è zero, la funzione hook riceve gli eventi specificati da tutti i thread in tale processo. Se il parametro idProcess è zero e idThread è diverso da zero, la funzione hook riceve gli eventi specificati solo dal thread specificato da idThread. Se entrambi sono zero, la funzione hook riceve gli eventi specificati da tutti i thread e i processi.
I client possono chiamare SetWinEventHook più volte se vogliono registrare funzioni hook aggiuntive o restare in ascolto di eventi aggiuntivi.
Il thread client che chiama SetWinEventHook deve avere un ciclo di messaggi per ricevere gli eventi.
Quando si usa SetWinEventHook per impostare un callback nel codice gestito, è consigliabile usare la struttura GCHandle per evitare eccezioni. Ciò indica al Garbage Collector di non spostare il callback.
Per gli eventi out-of-context, l'evento viene recapitato nello stesso thread che ha chiamato SetWinEventHook. In alcune situazioni, anche se si richiedono eventi WINEVENT_INCONTEXT, gli eventi verranno comunque recapitati fuori contesto. Questi scenari includono eventi provenienti da finestre della console ed eventi di processi con una profondità di bit diversa (64 bit rispetto a 32 bit) rispetto al chiamante.
Mentre una funzione hook elabora un evento, è possibile che vengano attivati eventi aggiuntivi, che possono causare la reinserizione della funzione hook prima del completamento dell'elaborazione per l'evento originale. Il problema della reentrancy nelle funzioni hook è che gli eventi vengono completati fuori sequenza, a meno che la funzione hook non gestisca questa situazione. Per altre informazioni, vedere Protezione dalla reentrancy.
Sviluppo di app di Windows Store Se dwFlags è WINEVENT_INCONTEXT AND (idProcess = 0 | idThread = 0), le DLL hook finestra non vengono caricate in-process per i processi dell'app di Windows Store e il processo broker Windows Runtime a meno che non siano installati dai processi uiAccess (strumenti di accessibilità). La notifica viene recapitata nel thread del programma di installazione.
Questo comportamento è simile a quello che accade quando si verifica una mancata corrispondenza dell'architettura tra la DLL hook e il processo dell'applicazione di destinazione, ad esempio quando la DLL hook è a 32 bit e il processo dell'applicazione a 64 bit.
Esempio
Il codice di esempio seguente mostra come un'applicazione client potrebbe restare in ascolto degli eventi menu-start e menu-end. Per semplicità, il gestore eventi invia solo alcune informazioni all'output 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();
}
}
Requisiti
| Requisito | Valore |
|---|---|
| Client minimo supportato | Windows 2000 Professional [solo app desktop] |
| Server minimo supportato | Windows Server 2003 [solo app desktop] |
| Piattaforma di destinazione | Windows |
| Intestazione | winuser.h (include Windows.h) |
| Libreria | User32.lib |
| DLL | User32.dll |
| Componente ridistribuibile | Accessibilità attiva 1.3 RDK in Windows NT 4.0 con SP6 e versioni successive e Windows 95 |