Função SetWinEventHook (winuser.h)

Define uma função de gancho de evento para um intervalo de eventos.

Sintaxe

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

Parâmetros

[in] eventMin

Tipo: UINT

Especifica a constante de evento para o valor de evento mais baixo no intervalo de eventos que são manipulados pela função hook. Esse parâmetro pode ser definido como EVENT_MIN para indicar o menor valor de evento possível.

[in] eventMax

Tipo: UINT

Especifica a constante de evento para o valor de evento mais alto no intervalo de eventos que são manipulados pela função hook. Esse parâmetro pode ser definido como EVENT_MAX para indicar o valor de evento mais alto possível.

[in] hmodWinEventProc

Tipo: HMODULE

Manipule para a DLL que contém a função hook em lpfnWinEventProc, se o sinalizador WINEVENT_INCONTEXT for especificado no parâmetro dwFlags . Se a função hook não estiver localizada em uma DLL ou se o sinalizador WINEVENT_OUTOFCONTEXT for especificado, esse parâmetro será NULL.

[in] pfnWinEventProc

Tipo: WINEVENTPROC

Ponteiro para a função de gancho de evento. Para obter mais informações sobre essa função, consulte WinEventProc.

[in] idProcess

Tipo: DWORD

Especifica a ID do processo do qual a função hook recebe eventos. Especifique zero (0) para receber eventos de todos os processos na área de trabalho atual.

[in] idThread

Tipo: DWORD

Especifica a ID do thread do qual a função hook recebe eventos. Se esse parâmetro for zero, a função hook será associada a todos os threads existentes na área de trabalho atual.

[in] dwFlags

Tipo: UINT

Valores de sinalizador que especificam o local da função de gancho e dos eventos a serem ignorados. Os seguintes sinalizadores são válidos:

Valor Significado
WINEVENT_INCONTEXT
A DLL que contém a função de retorno de chamada é mapeada para o espaço de endereço do processo que gera o evento. Com esse sinalizador, o sistema envia notificações de evento para a função de retorno de chamada conforme elas ocorrem. A função hook deve estar em uma DLL quando esse sinalizador for especificado. Esse sinalizador não tem efeito quando o processo de chamada e o processo de geração não são processos de 32 bits ou 64 bits ou quando o processo de geração é um aplicativo de console. Para obter mais informações, consulte Funções de gancho no contexto.
WINEVENT_OUTOFCONTEXT
A função de retorno de chamada não é mapeada para o espaço de endereço do processo que gera o evento. Como a função hook é chamada entre os limites do processo, o sistema deve enfileirar eventos. Embora esse método seja assíncrono, é garantido que os eventos estejam em ordem sequencial. Para obter mais informações, consulte Funções de gancho fora de contexto.
WINEVENT_SKIPOWNPROCESS
Impede que essa instância do gancho receba os eventos gerados por threads nesse processo. Esse sinalizador não impede que threads gerem eventos.
WINEVENT_SKIPOWNTHREAD
Impede que essa instância do gancho receba os eventos gerados pelo thread que está registrando esse gancho.
 

As seguintes combinações de sinalizadores são válidas:

  • WINEVENT_INCONTEXT | WINEVENT_SKIPOWNPROCESS
  • WINEVENT_INCONTEXT | WINEVENT_SKIPOWNTHREAD
  • WINEVENT_OUTOFCONTEXT | WINEVENT_SKIPOWNPROCESS
  • WINEVENT_OUTOFCONTEXT | WINEVENT_SKIPOWNTHREAD
Além disso, os aplicativos cliente podem especificar WINEVENT_INCONTEXT ou WINEVENT_OUTOFCONTEXT sozinhos.

Consulte a seção Comentários para obter informações sobre o desenvolvimento de aplicativos da Windows Store.

Retornar valor

Tipo: HWINEVENTHOOK

Se tiver êxito, retornará um valor HWINEVENTHOOK que identifica essa instância de gancho de evento. Os aplicativos salvam esse valor retornado para usá-lo com a função UnhookWinEvent .

Se não tiver êxito, retornará zero.

Comentários

Essa função permite que os clientes especifiquem em quais processos e threads eles estão interessados.

Se o parâmetro idProcess for diferente de zero e idThread for zero, a função hook receberá os eventos especificados de todos os threads nesse processo. Se o parâmetro idProcess for zero e idThread não for zero, a função hook receberá os eventos especificados somente do thread especificado por idThread. Se ambos forem zero, a função hook receberá os eventos especificados de todos os threads e processos.

Os clientes podem chamar SetWinEventHook várias vezes se quiserem registrar funções de gancho adicionais ou escutar eventos adicionais.

O thread do cliente que chama SetWinEventHook deve ter um loop de mensagem para receber eventos.

Ao usar SetWinEventHook para definir um retorno de chamada no código gerenciado, você deve usar a estrutura GCHandle para evitar exceções. Isso informa ao coletor de lixo para não mover o retorno de chamada.

Para eventos fora de contexto, o evento é entregue no mesmo thread chamado SetWinEventHook. Em algumas situações, mesmo que você solicite eventos WINEVENT_INCONTEXT, os eventos ainda serão entregues fora de contexto. Esses cenários incluem eventos de janelas de console e eventos de processos que têm uma profundidade de bit diferente (64 bits versus 32 bits) do que o chamador.

Enquanto uma função de gancho processa um evento, eventos adicionais podem ser disparados, o que pode fazer com que a função hook seja reentrada antes que o processamento do evento original seja concluído. O problema com a reentrância em funções de gancho é que os eventos são concluídos fora da sequência, a menos que a função hook lide com essa situação. Para obter mais informações, consulte Proteção contra a reentrada.

Desenvolvimento de aplicativos da Windows Store Se dwFlags for WINEVENT_INCONTEXT AND (idProcess = 0 | idThread = 0), as DLLs do gancho de janela não serão carregadas em processo para os processos de aplicativo da Windows Store e o processo do agente Windows Runtime, a menos que sejam instaladas por processos UIAccess (ferramentas de acessibilidade). A notificação é entregue no thread do instalador.

Esse comportamento é semelhante ao que acontece quando há uma incompatibilidade de arquitetura entre a DLL do gancho e o processo de aplicativo de destino, por exemplo, quando a DLL do gancho é de 32 bits e o processo do aplicativo de 64 bits.

Exemplos

O código de exemplo a seguir mostra como um aplicativo cliente pode escutar eventos de início de menu e menu-end. Para simplificar, o manipulador de eventos apenas envia algumas informações para a saída padrão.


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

Requisitos

Requisito Valor
Cliente mínimo com suporte Windows 2000 Professional [somente aplicativos da área de trabalho]
Servidor mínimo com suporte Windows Server 2003 [somente aplicativos da área de trabalho]
Plataforma de Destino Windows
Cabeçalho winuser.h (inclua Windows.h)
Biblioteca User32.lib
DLL User32.dll
Redistribuível Active Accessibility 1.3 RDK no Windows NT 4.0 com SP6 e posterior e Windows 95

Confira também

Registrando uma função hook

UnhookWinEvent

WinEventProc