Função SetWindowsHookExW (winuser.h)
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 SetWindowsHookExW(
[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 ser um dos valores a seguir.
| Valor | Significado |
|---|---|
|
Instala um procedimento de gancho que monitora as mensagens antes que o sistema as envie para o procedimento da janela de destino. Para obter mais informações, consulte o procedimento CallWndProc hook. |
|
Instala um procedimento de gancho que monitora as mensagens depois que elas são processadas pelo procedimento da janela de destino. Para obter mais informações, consulte a função de retorno de chamada HOOKPROC procedimento de gancho. |
|
Instala um procedimento de gancho que recebe notificações úteis para um aplicativo CBT. Para obter mais informações, consulte o procedimento de gancho de CBTProc. |
|
Instala um procedimento de gancho útil para depurar outros procedimentos de gancho. Para obter mais informações, consulte o procedimento DebugProc hook. |
|
Instala um procedimento de gancho que será chamado quando o thread de 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 ForegroundIdleProc hook. |
|
Instala um procedimento de gancho que monitora mensagens postadas em uma fila de mensagens. Para obter mais informações, consulte o procedimento de gancho de getMsgProc |
|
Aviso As APIs do Journaling Hooks não têm suporte a partir do Windows 11 e serão removidas em uma versão futura. Por isso, é altamente recomendável chamar a API SendInput TextInput. Instala um procedimento de gancho que posta mensagens gravadas anteriormente por um procedimento de gancho de WH_JOURNALRECORD. Para obter mais informações, consulte o procedimento JournalPlaybackProc hook. |
|
Aviso As APIs do Journaling Hooks não têm suporte a partir do Windows 11 e serão removidas em uma versão futura. Por isso, é altamente recomendável chamar 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 |
|
Instala um procedimento de gancho que monitora mensagens de pressionamento de tecla. Para obter mais informações, consulte o procedimento KeyboardProc hook. |
|
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 de |
|
Instala um procedimento de gancho que monitora mensagens do mouse. Para obter mais informações, consulte o procedimento de gancho |
|
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 de lowlevelMouseProc |
|
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 MessageProc hook. |
|
Instala um procedimento de gancho que recebe notificações úteis para aplicativos de shell. Para obter mais informações, consulte o procedimento ShellProc hook. |
|
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 de |
[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 deve 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.
Valor de retorno
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.
Observações
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 que chamou 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 instalar um gancho global no Windows de 64 bits, o gancho de 64 bits será injetado em cada processo de 64 bits, enquanto todos os processos de 32 bits usarão 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 função para encadear para o próximo procedimento de gancho é opcional, mas é altamente recomendável; caso contrário, outros aplicativos que instalaram ganchos 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.
Em aplicativos .NET, você deve garantir que o retorno de chamada não seja movido pelo coletor de lixo (caso contrário, seu aplicativo falhará com uma ExecutionEngineException). Uma maneira de fazer isso é fazendo do retorno de chamada um método estático da sua classe.
Antes de encerrar, um aplicativo deve chamar a função UnhookWindowsHookEx função para liberar recursos do sistema associados ao gancho.
O escopo de um gancho depende do tipo de gancho. Alguns ganchos podem ser definidos apenas com escopo global; outros também podem ser definidos para apenas um thread específico, conforme mostrado na tabela a seguir.
| Gancho | Âmbito |
|---|---|
| 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 que processa o gancho. Para esses ganchos, é possível que os ganchos de 32 bits 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 finalidade 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.
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 do Windows Runtime, a menos que sejam instaladas por processos UIAccess (ferramentas de acessibilidade). A notificação é entregue no thread do instalador para estes ganchos:
- WH_JOURNALPLAYBACK
- WH_JOURNALRECORD
- WH_KEYBOARD
- WH_KEYBOARD_LL
- WH_MOUSE
- WH_MOUSE_LL
Exemplos
Para obter um exemplo, consulte Instalando e liberando procedimentos de gancho.
Nota
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 do pré-processador UNICODE. A combinação do uso do alias neutro de codificação com código que não é neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Conventions for Function Prototypes.
Requisitos
| Requisito | Valor |
|---|---|
| de cliente com suporte mínimo | Windows 2000 Professional [somente aplicativos da área de trabalho] |
| servidor com suporte mínimo | Windows 2000 Server [somente aplicativos da área de trabalho] |
| da Plataforma de Destino |
Windows |
| cabeçalho | winuser.h (inclua Windows.h) |
| biblioteca | User32.lib |
| de DLL |
User32.dll |
| conjunto de API | ext-ms-win-ntuser-window-l1-1-0 (introduzido no Windows 8) |
Consulte também
ForegroundIdleProc
do MouseProc
Conceitual