Función SetWindowsHookExW (winuser.h)

Artículo
07/01/2023

Instala un procedimiento de enlace definido por la aplicación en una cadena de enlace. Instalaría un procedimiento de enlace para supervisar el sistema para determinados tipos de eventos. Estos eventos están asociados a un subproceso específico o a todos los subprocesos del mismo escritorio que el subproceso que llama.

Sintaxis

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

Parámetros

[in] idHook

Tipo: int

Tipo de procedimiento de enlace que se va a instalar. Este parámetro puede ser uno de los siguientes valores.

Valor	Significado
WH_CALLWNDPROC 4	Instala un procedimiento de enlace que supervisa los mensajes antes de que el sistema los envíe al procedimiento de la ventana de destino. Para obtener más información, consulte el procedimiento de enlace callWndProc .
WH_CALLWNDPROCRET 12	Instala un procedimiento de enlace que supervisa los mensajes una vez procesados por el procedimiento de ventana de destino. Para obtener más información, consulte el procedimiento de enlace función de devolución de llamada HOOKPROC .
WH_CBT 5	Instala un procedimiento de enlace que recibe notificaciones útiles para una aplicación CBT. Para obtener más información, consulte el procedimiento de enlace CBTProc.
WH_DEBUG 9	Instala un procedimiento de enlace útil para depurar otros procedimientos de enlace. Para obtener más información, consulte el procedimiento de enlace DebugProc.
WH_FOREGROUNDIDLE 11	Instala un procedimiento de enlace al que se llamará cuando el subproceso en primer plano de la aplicación esté a punto de estar inactivo. Este enlace es útil para realizar tareas de prioridad baja durante el tiempo de inactividad. Para obtener más información, consulte el procedimiento de enlace ForegroundIdleProc.
WH_GETMESSAGE 3	Instala un procedimiento de enlace que supervisa los mensajes publicados en una cola de mensajes. Para obtener más información, consulte el procedimiento de enlace GetMsgProc.
WH_JOURNALPLAYBACK 1	Advertencia Las API de enlaces en diario no son compatibles a partir de Windows 11 y se quitarán en una versión futura. Por este motivo, se recomienda encarecidamente llamar a la API SendInput TextInput en su lugar. Instala un procedimiento de enlace que publica mensajes grabados previamente por un procedimiento de enlace de WH_JOURNALRECORD. Para obtener más información, consulte el procedimiento de enlace JournalPlaybackProc.
WH_JOURNALRECORD 0	Advertencia Las API de enlaces en diario no son compatibles a partir de Windows 11 y se quitarán en una versión futura. Por este motivo, se recomienda encarecidamente llamar a la API SendInput TextInput en su lugar. Instala un procedimiento de enlace que registra los mensajes de entrada publicados en la cola de mensajes del sistema. Este enlace es útil para grabar macros. Para obtener más información, consulte el procedimiento de enlace JournalRecordProc.
WH_KEYBOARD 2	Instala un procedimiento de enlace que supervisa los mensajes de pulsación de tecla. Para obtener más información, consulte el procedimiento de enlace de KeyboardProc.
WH_KEYBOARD_LL 13	Instala un procedimiento de enlace que supervisa los eventos de entrada de teclado de bajo nivel. Para obtener más información, consulte el procedimiento de enlace LowLevelKeyboardProc.
WH_MOUSE 7	Instala un procedimiento de enlace que supervisa los mensajes del mouse. Para obtener más información, consulte el procedimiento de enlace de mouseProc .
WH_MOUSE_LL 14	Instala un procedimiento de enlace que supervisa los eventos de entrada del mouse de bajo nivel. Para obtener más información, consulte el procedimiento de enlace LowLevelMouseProc.
WH_MSGFILTER -1	Instala un procedimiento de enlace que supervisa los mensajes generados como resultado de un evento de entrada en un cuadro de diálogo, un cuadro de mensaje, un menú o una barra de desplazamiento. Para obtener más información, consulte el procedimiento de enlace de MessageProc.
WH_SHELL 10	Instala un procedimiento de enlace que recibe notificaciones útiles para las aplicaciones de shell. Para obtener más información, consulte el procedimiento de enlace shellProc .
WH_SYSMSGFILTER 6	Instala un procedimiento de enlace que supervisa los mensajes generados como resultado de un evento de entrada en un cuadro de diálogo, un cuadro de mensaje, un menú o una barra de desplazamiento. El procedimiento de enlace supervisa estos mensajes para todas las aplicaciones del mismo escritorio que el subproceso que realiza la llamada. Para obtener más información, consulte el procedimiento de enlace SysMsgProc.

[in] lpfn

Tipo: HOOKPROC

Puntero al procedimiento de enlace. Si el parámetro dwThreadId es cero o especifica el identificador de un subproceso creado por un proceso diferente, el parámetro lpfn debe apuntar a un procedimiento de enlace en un archivo DLL. De lo contrario, lpfn puede apuntar a un procedimiento de enlace en el código asociado al proceso actual.

[in] hmod

Tipo: HINSTANCE

Identificador del archivo DLL que contiene el procedimiento de enlace al que apunta el parámetro lpfn. El parámetro hMod debe establecerse en null si el parámetro dwThreadId especifica un subproceso creado por el proceso actual y si el procedimiento de enlace está dentro del código asociado al proceso actual.

[in] dwThreadId

Tipo: DWORD de

Identificador del subproceso con el que se va a asociar el procedimiento de enlace. En el caso de las aplicaciones de escritorio, si este parámetro es cero, el procedimiento de enlace está asociado a todos los subprocesos existentes que se ejecutan en el mismo escritorio que el subproceso que realiza la llamada. Para las aplicaciones de la Tienda Windows, consulta la sección Comentarios.

Valor devuelto

Tipo: HHOOK

Si la función se ejecuta correctamente, el valor devuelto es el identificador del procedimiento de enlace.

Si se produce un error en la función, el valor devuelto es NULL. Para obtener información de error extendida, llame a GetLastError.

Observaciones

setWindowsHookEx se puede usar para insertar un archivo DLL en otro proceso. No se puede insertar un archivo DLL de 32 bits en un proceso de 64 bits y no se puede insertar un archivo DLL de 64 bits en un proceso de 32 bits. Si una aplicación requiere el uso de enlaces en otros procesos, es necesario que una llamada de aplicación de 32 bits SetWindowsHookEx para insertar un archivo DLL de 32 bits en procesos de 32 bits y una llamada de aplicación de 64 bits SetWindowsHookEx para insertar un archivo DLL de 64 bits en procesos de 64 bits. Los archivos DLL de 32 y 64 bits deben tener nombres diferentes.

Dado que los enlaces se ejecutan en el contexto de una aplicación, deben coincidir con el "bitness" de la aplicación. Si una aplicación de 32 bits instala un enlace global en Windows de 64 bits, el enlace de 32 bits se inserta en cada proceso de 32 bits (se aplican los límites de seguridad habituales). En un proceso de 64 bits, los subprocesos siguen marcados como "enganchados". Sin embargo, dado que una aplicación de 32 bits debe ejecutar el código de enlace, el sistema ejecuta el enlace en el contexto de la aplicación de enlace; en concreto, en el subproceso que llamó a SetWindowsHookEx. Esto significa que la aplicación de enlace debe seguir bombeando mensajes o podría bloquear el funcionamiento normal de los procesos de 64 bits.

Si una aplicación de 64 bits instala un enlace global en Windows de 64 bits, el enlace de 64 bits se inserta en cada proceso de 64 bits, mientras que todos los procesos de 32 bits usan una devolución de llamada a la aplicación de enlace.

Para enlazar todas las aplicaciones en el escritorio de una instalación de Windows de 64 bits, instale un enlace global de 32 bits y un enlace global de 64 bits, cada uno de los procesos adecuados y asegúrese de seguir bombeando mensajes en la aplicación de enlace para evitar el bloqueo del funcionamiento normal. Si ya tiene una aplicación de enlace global de 32 bits y no necesita ejecutarse en el contexto de cada aplicación, es posible que no necesite crear una versión de 64 bits.

Puede producirse un error si el parámetro hMod es NULL y el parámetro dwThreadId es cero o especifica el identificador de un subproceso creado por otro proceso.

Llamar a la función CallNextHookEx función para encadenar al siguiente procedimiento de enlace es opcional, pero es muy recomendable; De lo contrario, otras aplicaciones que tienen enlaces instalados no recibirán notificaciones de enlace y pueden comportarse incorrectamente como resultado. Debe llamar a CallNextHookEx a menos que necesite impedir que otras aplicaciones vean la notificación.

En las aplicaciones .NET, debe asegurarse de que el recolector de elementos no utilizados no mueve la devolución de llamada (de lo contrario, la aplicación se bloqueará con una excepción ExecutionEngineException). Una manera de hacerlo es hacer que la devolución de llamada sea un método estático de la clase.

Antes de finalizar, una aplicación debe llamar a la función UnhookWindowsHookEx función para liberar recursos del sistema asociados al enlace.

El ámbito de un enlace depende del tipo de enlace. Algunos enlaces solo se pueden establecer con ámbito global; Otros también se pueden establecer para solo un subproceso específico, como se muestra en la tabla siguiente.

Gancho	Alcance
WH_CALLWNDPROC	Subproceso o global
WH_CALLWNDPROCRET	Subproceso o global
WH_CBT	Subproceso o global
WH_DEBUG	Subproceso o global
WH_FOREGROUNDIDLE	Subproceso o global
WH_GETMESSAGE	Subproceso o global
WH_JOURNALPLAYBACK	Solo global
WH_JOURNALRECORD	Solo global
WH_KEYBOARD	Subproceso o global
WH_KEYBOARD_LL	Solo global
WH_MOUSE	Subproceso o global
WH_MOUSE_LL	Solo global
WH_MSGFILTER	Subproceso o global
WH_SHELL	Subproceso o global
WH_SYSMSGFILTER	Solo global

Para un tipo de enlace especificado, los enlaces de subproceso se llaman primero y, a continuación, los enlaces globales. Tenga en cuenta que se puede llamar a los enlaces de WH_MOUSE, WH_KEYBOARD, WH_JOURNAL*, WH_SHELL y de bajo nivel en el subproceso que instaló el enlace en lugar del subproceso que procesa el enlace. Para estos enlaces, es posible que se llame a los enlaces de 32 y 64 bits si un enlace de 32 bits está por delante de un enlace de 64 bits en la cadena de ganchos.

Los enlaces globales son un recurso compartido y la instalación de una afecta a todas las aplicaciones del mismo escritorio que el subproceso que realiza la llamada. Todas las funciones de enlace global deben estar en bibliotecas. Los enlaces globales deben restringirse a aplicaciones de uso especial o usarse como ayuda de desarrollo durante la depuración de aplicaciones. Las bibliotecas que ya no necesitan un enlace deben quitar su procedimiento de enlace.

aplicaciones de la Tienda Windows: Si dwThreadId es cero, los archivos DLL de enlace de ventana no se cargan en proceso para los procesos de la aplicación de la Tienda Windows y el proceso del agente de Windows Runtime a menos que los instalen los procesos uiAccess (herramientas de accesibilidad). La notificación se entrega en el subproceso del instalador para estos enlaces:

WH_JOURNALPLAYBACK
WH_JOURNALRECORD
WH_KEYBOARD
WH_KEYBOARD_LL
WH_MOUSE
WH_MOUSE_LL

Este comportamiento es similar a lo que sucede cuando hay una discrepancia de arquitectura entre el archivo DLL de enlace y el proceso de aplicación de destino, por ejemplo, cuando el archivo DLL de enlace es de 32 bits y el proceso de aplicación de 64 bits.

Ejemplos

Para obtener un ejemplo, vea Procedimientos de instalación y liberación de enlaces.

Nota

El encabezado winuser.h define SetWindowsHookEx como alias que selecciona automáticamente la versión ANSI o Unicode de esta función en función de la definición de la constante de preprocesador UNICODE. La combinación del uso del alias neutral de codificación con código que no es neutral de codificación puede dar lugar a errores de coincidencia que dan lugar a errores de compilación o tiempo de ejecución. Para obtener más información, vea Conventions for Function Prototypes.

Requisitos

Requisito	Valor
cliente mínimo admitido	Windows 2000 Professional [solo aplicaciones de escritorio]
servidor mínimo admitido	Windows 2000 Server [solo aplicaciones de escritorio]
de la plataforma de destino de	Windows
encabezado de	winuser.h (incluya Windows.h)
biblioteca de	User32.lib
DLL de	User32.dll
conjunto de API de	ext-ms-win-ntuser-window-l1-1-0 (introducido en Windows 8)