Condividi tramite


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
WINEVENT_INCONTEXT
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.
WINEVENT_OUTOFCONTEXT
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.
WINEVENT_SKIPOWNPROCESS
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.
WINEVENT_SKIPOWNTHREAD
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
Inoltre, le applicazioni client possono specificare WINEVENT_INCONTEXT o WINEVENT_OUTOFCONTEXT da sole.

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

Vedi anche

Registrazione di una funzione hook

UnhookWinEvent

WinEventProc