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 |
|---|---|
|
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. |
|
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. |
|
Impede que essa instância do gancho receba os eventos gerados por threads nesse processo. Esse sinalizador não impede que threads gerem eventos. |
|
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
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 |