Função SetWindowsHookExA (winuser.h)

Artigo
07/01/2023

Instala um procedimento de gancho definido pelo aplicativo em uma cadeia de ganchos. Você instalaria um procedimento de gancho para monitorar o sistema para determinados tipos de eventos. Esses eventos são associados a um thread específico ou a todos os threads na mesma área de trabalho que o thread de chamada.

Sintaxe

HHOOK SetWindowsHookExA(
  [in] int       idHook,
  [in] HOOKPROC  lpfn,
  [in] HINSTANCE hmod,
  [in] DWORD     dwThreadId
);

Parâmetros

[in] idHook

Tipo: int

O tipo de procedimento de gancho a ser instalado. Esse parâmetro pode usar um dos valores a seguir.

Valor	Significado
WH_CALLWNDPROC 4	Instala um procedimento de gancho que monitora mensagens antes que o sistema as envie para o procedimento de janela de destino. Para obter mais informações, consulte o procedimento de gancho CallWndProc .
WH_CALLWNDPROCRET 12	Instala um procedimento de gancho que monitora mensagens depois que elas são processadas pelo procedimento da janela de destino. Para obter mais informações, consulte o procedimento de gancho [função de retorno de chamada HOOKPROC](nc-winuser-hookproc.md).
WH_CBT 5	Instala um procedimento de gancho que recebe notificações úteis para um aplicativo CBT. Para obter mais informações, consulte o procedimento de gancho CBTProc .
WH_DEBUG 9	Instala um procedimento de gancho útil para depurar outros procedimentos de gancho. Para obter mais informações, consulte o procedimento de gancho DebugProc .
WH_FOREGROUNDIDLE 11	Instala um procedimento de gancho que será chamado quando o thread em primeiro plano do aplicativo estiver prestes a ficar ocioso. Esse gancho é útil para executar tarefas de baixa prioridade durante o tempo ocioso. Para obter mais informações, consulte o procedimento de gancho ForegroundIdleProc .
WH_GETMESSAGE 3	Instala um procedimento de gancho que monitora mensagens postadas em uma fila de mensagens. Para obter mais informações, consulte o procedimento de gancho GetMsgProc .
WH_JOURNALPLAYBACK 1	Aviso Windows 11 e mais recentes: não há suporte para APIs de gancho de registro em diário. Em vez disso, recomendamos usar a API SendInput TextInput. Instala um procedimento de gancho que posta mensagens registradas anteriormente por um procedimento de gancho de WH_JOURNALRECORD . Para obter mais informações, consulte o procedimento de gancho JournalPlaybackProc .
WH_JOURNALRECORD 0	Aviso Windows 11 e mais recentes: não há suporte para APIs de gancho de registro em diário. Em vez disso, recomendamos usar a API SendInput TextInput. Instala um procedimento de gancho que registra mensagens de entrada postadas na fila de mensagens do sistema. Esse gancho é útil para gravar macros. Para obter mais informações, consulte o procedimento de gancho JournalRecordProc .
WH_KEYBOARD 2	Instala um procedimento de gancho que monitora mensagens de pressionamento de tecla. Para obter mais informações, consulte o procedimento de gancho KeyboardProc .
WH_KEYBOARD_LL 13	Instala um procedimento de gancho que monitora eventos de entrada de teclado de baixo nível. Para obter mais informações, consulte o procedimento de gancho [LowLevelKeyboardProc](/windows/win32/winmsg/lowlevelkeyboardproc).
WH_MOUSE 7	Instala um procedimento de gancho que monitora mensagens do mouse. Para obter mais informações, consulte o procedimento de gancho MouseProc .
WH_MOUSE_LL 14	Instala um procedimento de gancho que monitora eventos de entrada de mouse de baixo nível. Para obter mais informações, consulte o procedimento de gancho LowLevelMouseProc .
WH_MSGFILTER -1	Instala um procedimento de gancho que monitora mensagens geradas como resultado de um evento de entrada em uma caixa de diálogo, caixa de mensagem, menu ou barra de rolagem. Para obter mais informações, consulte o procedimento de gancho MessageProc .
WH_SHELL 10	Instala um procedimento de gancho que recebe notificações úteis para aplicativos de shell. Para obter mais informações, consulte o procedimento de gancho ShellProc .
WH_SYSMSGFILTER 6	Instala um procedimento de gancho que monitora mensagens geradas como resultado de um evento de entrada em uma caixa de diálogo, caixa de mensagem, menu ou barra de rolagem. O procedimento de gancho monitora essas mensagens para todos os aplicativos na mesma área de trabalho que o thread de chamada. Para obter mais informações, consulte o procedimento de gancho SysMsgProc .

[in] lpfn

Tipo: HOOKPROC

Um ponteiro para o procedimento de gancho. Se o parâmetro dwThreadId for zero ou especificar o identificador de um thread criado por um processo diferente, o parâmetro lpfn deverá apontar para um procedimento de gancho em uma DLL. Caso contrário, lpfn pode apontar para um procedimento de gancho no código associado ao processo atual.

[in] hmod

Tipo: HINSTANCE

Um identificador para a DLL que contém o procedimento de gancho apontado pelo parâmetro lpfn . O parâmetro hMod deverá ser definido como NULL se o parâmetro dwThreadId especificar um thread criado pelo processo atual e se o procedimento de gancho estiver dentro do código associado ao processo atual.

[in] dwThreadId

Tipo: DWORD

O identificador do thread ao qual o procedimento de gancho deve ser associado. Para aplicativos da área de trabalho, se esse parâmetro for zero, o procedimento de gancho será associado a todos os threads existentes em execução na mesma área de trabalho que o thread de chamada. Para aplicativos da Windows Store, consulte a seção Comentários.

Retornar valor

Tipo: HHOOK

Se a função for bem-sucedida, o valor retornado será o identificador para o procedimento de gancho.

Se a função falhar, o valor retornado será NULL. Para obter informações de erro estendidas, chame GetLastError.

Comentários

SetWindowsHookEx pode ser usado para injetar uma DLL em outro processo. Uma DLL de 32 bits não pode ser injetada em um processo de 64 bits e uma DLL de 64 bits não pode ser injetada em um processo de 32 bits. Se um aplicativo exigir o uso de ganchos em outros processos, será necessário que um aplicativo de 32 bits chame SetWindowsHookEx para injetar uma DLL de 32 bits em processos de 32 bits e uma chamada de aplicativo de 64 bits SetWindowsHookEx para injetar uma DLL de 64 bits em processos de 64 bits. As DLLs de 32 bits e 64 bits devem ter nomes diferentes.

Como os ganchos são executados no contexto de um aplicativo, eles devem corresponder à "bitness" do aplicativo. Se um aplicativo de 32 bits instalar um gancho global no Windows de 64 bits, o gancho de 32 bits será injetado em cada processo de 32 bits (os limites de segurança usuais se aplicam). Em um processo de 64 bits, os threads ainda são marcados como "fisgados". No entanto, como um aplicativo de 32 bits deve executar o código de gancho, o sistema executa o gancho no contexto do aplicativo de conexão; especificamente, no thread chamado SetWindowsHookEx. Isso significa que o aplicativo de conexão deve continuar a bombear mensagens ou pode bloquear o funcionamento normal dos processos de 64 bits.

Se um aplicativo de 64 bits instala um gancho global no Windows de 64 bits, o gancho de 64 bits é injetado em cada processo de 64 bits, enquanto todos os processos de 32 bits usam um retorno de chamada para o aplicativo de conexão.

Para conectar todos os aplicativos na área de trabalho de uma instalação do Windows de 64 bits, instale um gancho global de 32 bits e um gancho global de 64 bits, cada um dos processos apropriados, e certifique-se de continuar bombeando mensagens no aplicativo de conexão para evitar bloquear o funcionamento normal. Se você já tiver um aplicativo de conexão global de 32 bits e ele não precisar ser executado no contexto de cada aplicativo, talvez não seja necessário criar uma versão de 64 bits.

Um erro poderá ocorrer se o parâmetro hMod for NULL e o parâmetro dwThreadId for zero ou especificar o identificador de um thread criado por outro processo.

Chamar a função CallNextHookEx para encadear para o próximo procedimento de gancho é opcional, mas é altamente recomendável; caso contrário, outros aplicativos que têm ganchos instalados não receberão notificações de gancho e poderão se comportar incorretamente como resultado. Você deve chamar CallNextHookEx , a menos que seja absolutamente necessário impedir que a notificação seja vista por outros aplicativos.

Antes de encerrar, um aplicativo deve chamar a função UnhookWindowsHookEx para liberar recursos do sistema associados ao gancho.

O escopo de um gancho depende do tipo de gancho. Alguns ganchos só podem ser definidos com escopo global; outros também podem ser definidos apenas para um thread específico, conforme mostrado na tabela a seguir.

Gancho	Escopo
WH_CALLWNDPROC	Thread ou global
WH_CALLWNDPROCRET	Thread ou global
WH_CBT	Thread ou global
WH_DEBUG	Thread ou global
WH_FOREGROUNDIDLE	Thread ou global
WH_GETMESSAGE	Thread ou global
WH_JOURNALPLAYBACK	Somente global
WH_JOURNALRECORD	Somente global
WH_KEYBOARD	Thread ou global
WH_KEYBOARD_LL	Somente global
WH_MOUSE	Thread ou global
WH_MOUSE_LL	Somente global
WH_MSGFILTER	Thread ou global
WH_SHELL	Thread ou global
WH_SYSMSGFILTER	Somente global

Para um tipo de gancho especificado, os ganchos de thread são chamados primeiro e, em seguida, ganchos globais. Lembre-se de que os ganchos WH_MOUSE, WH_KEYBOARD, WH_JOURNAL*, WH_SHELL e de baixo nível podem ser chamados no thread que instalou o gancho em vez do thread processando o gancho. Para esses ganchos, é possível que os ganchos de 32 e 64 bits sejam chamados se um gancho de 32 bits estiver à frente de um gancho de 64 bits na cadeia de ganchos.

Os ganchos globais são um recurso compartilhado e a instalação de um afeta todos os aplicativos na mesma área de trabalho que o thread de chamada. Todas as funções de gancho global devem estar em bibliotecas. Os ganchos globais devem ser restritos a aplicativos de uso especial ou usar como um auxílio de desenvolvimento durante a depuração do aplicativo. Bibliotecas que não precisam mais de um gancho devem remover seu procedimento de gancho.

Desenvolvimento de aplicativos da Windows Store Se dwThreadId for zero, 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 de Windows Runtime, a menos que sejam instaladas por processos UIAccess (ferramentas de acessibilidade). A notificação é entregue no thread do instalador para esses ganchos:

WH_JOURNALPLAYBACK
WH_JOURNALRECORD
WH_KEYBOARD
WH_KEYBOARD_LL
WH_MOUSE
WH_MOUSE_LL

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

Para obter um exemplo, consulte Instalando e liberando procedimentos de gancho.

Observação

O cabeçalho winuser.h define SetWindowsHookEx como um alias que seleciona automaticamente a versão ANSI ou Unicode dessa função com base na definição da constante de pré-processador UNICODE. Misturar o uso do alias neutro de codificação com código que não seja neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Convenções para protótipos de função.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows 2000 Professional [somente aplicativos da área de trabalho]
Servidor mínimo com suporte	Windows 2000 Server [somente aplicativos da área de trabalho]
Plataforma de Destino	Windows
Cabeçalho	winuser.h (inclua Windows.h)
Biblioteca	User32.lib
DLL	User32.dll
Conjunto de APIs	ext-ms-win-ntuser-window-l1-1-0 (introduzido em Windows 8)