Función SetWinEventHook (winuser.h)
Establece una función de enlace de eventos para un intervalo de eventos.
Sintaxis
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 la constante de evento para el valor de evento más bajo en el intervalo de eventos que controla la función de enlace. Este parámetro se puede establecer en EVENT_MIN para indicar el valor de evento más bajo posible.
[in] eventMax
Tipo: UINT
Especifica la constante de evento para el valor de evento más alto en el intervalo de eventos que controla la función de enlace. Este parámetro se puede establecer en EVENT_MAX para indicar el valor de evento más alto posible.
[in] hmodWinEventProc
Tipo: HMODULE
Identificador del archivo DLL que contiene la función de enlace en lpfnWinEventProc, si se especifica la marca WINEVENT_INCONTEXT en el parámetro dwFlags . Si la función de enlace no se encuentra en un archivo DLL o si se especifica la marca WINEVENT_OUTOFCONTEXT, este parámetro es NULL.
[in] pfnWinEventProc
Tipo: WINEVENTPROC
Puntero a la función de enlace de eventos. Para obtener más información sobre esta función, vea WinEventProc.
[in] idProcess
Tipo: DWORD
Especifica el identificador del proceso desde el que la función de enlace recibe eventos. Especifique cero (0) para recibir eventos de todos los procesos del escritorio actual.
[in] idThread
Tipo: DWORD
Especifica el identificador del subproceso desde el que la función de enlace recibe eventos. Si este parámetro es cero, la función de enlace se asocia a todos los subprocesos existentes en el escritorio actual.
[in] dwFlags
Tipo: UINT
Valores de marca que especifican la ubicación de la función de enlace y de los eventos que se van a omitir. Las marcas siguientes son válidas:
| Valor | Significado |
|---|---|
|
El archivo DLL que contiene la función de devolución de llamada se asigna al espacio de direcciones del proceso que genera el evento. Con esta marca, el sistema envía notificaciones de eventos a la función de devolución de llamada a medida que se producen. La función de enlace debe estar en un archivo DLL cuando se especifica esta marca. Esta marca no tiene ningún efecto cuando el proceso de llamada y el proceso de generación no son procesos de 32 o 64 bits, o cuando el proceso de generación es una aplicación de consola. Para obtener más información, vea Funciones de enlace en contexto. |
|
La función de devolución de llamada no está asignada al espacio de direcciones del proceso que genera el evento. Dado que se llama a la función de enlace a través de los límites del proceso, el sistema debe poner en cola los eventos. Aunque este método es asincrónico, se garantiza que los eventos están en orden secuencial. Para obtener más información, vea Funciones de enlace fuera de contexto. |
|
Impide que esta instancia del enlace reciba los eventos generados por subprocesos en este proceso. Esta marca no impide que los subprocesos generen eventos. |
|
Impide que esta instancia del enlace reciba los eventos generados por el subproceso que registra este enlace. |
Las siguientes combinaciones de marcas son válidas:
- WINEVENT_INCONTEXT | WINEVENT_SKIPOWNPROCESS
- WINEVENT_INCONTEXT | WINEVENT_SKIPOWNTHREAD
- WINEVENT_OUTOFCONTEXT | WINEVENT_SKIPOWNPROCESS
- WINEVENT_OUTOFCONTEXT | WINEVENT_SKIPOWNTHREAD
Consulta la sección Comentarios para obtener información sobre el desarrollo de aplicaciones de la Tienda Windows.
Valor devuelto
Tipo: HWINEVENTHOOK
Si se ejecuta correctamente, devuelve un valor HWINEVENTHOOK que identifica esta instancia de enlace de eventos. Las aplicaciones guardan este valor devuelto para usarlo con la función UnhookWinEvent .
Si no se realiza correctamente, devuelve cero.
Comentarios
Esta función permite a los clientes especificar qué procesos y subprocesos están interesados.
Si el parámetro idProcess es distinto de cero y idThread es cero, la función de enlace recibe los eventos especificados de todos los subprocesos de ese proceso. Si el parámetro idProcess es cero y idThread es distinto de cero, la función de enlace recibe los eventos especificados solo del subproceso especificado por idThread. Si ambos son cero, la función de enlace recibe los eventos especificados de todos los subprocesos y procesos.
Los clientes pueden llamar a SetWinEventHook varias veces si desean registrar funciones de enlace adicionales o escuchar eventos adicionales.
El subproceso de cliente que llama a SetWinEventHook debe tener un bucle de mensajes para recibir eventos.
Al usar SetWinEventHook para establecer una devolución de llamada en código administrado, debe usar la estructura GCHandle para evitar excepciones. Esto indica al recolector de elementos no utilizados que no mueva la devolución de llamada.
En el caso de los eventos fuera del contexto, el evento se entrega en el mismo subproceso que llamó a SetWinEventHook. En algunas situaciones, incluso si solicita eventos WINEVENT_INCONTEXT, los eventos se seguirán entregando fuera del contexto. Estos escenarios incluyen eventos de ventanas de consola y eventos de procesos que tienen una profundidad de bits diferente (64 bits frente a 32 bits) que el autor de la llamada.
Mientras una función de enlace procesa un evento, se pueden desencadenar eventos adicionales, lo que puede hacer que la función de enlace se vuelva a escribir antes de que finalice el procesamiento del evento original. El problema con la reentrada en las funciones de enlace es que los eventos se completan fuera de secuencia a menos que la función de enlace controle esta situación. Para obtener más información, vea Protección contra reentrada.
Desarrollo de aplicaciones de la Tienda Windows Si dwFlags es WINEVENT_INCONTEXT AND (idProcess = 0 | idThread = 0), 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 de agente de Windows Runtime a menos que los instalen los procesos de UIAccess (herramientas de accesibilidad). La notificación se entrega en el subproceso del instalador.
Este comportamiento es similar al que ocurre 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
En el código de ejemplo siguiente se muestra cómo una aplicación cliente puede escuchar eventos menu-start y menu-end. Para simplificar, el controlador de eventos simplemente envía información a la salida estándar.
// 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 | Value |
|---|---|
| Cliente mínimo compatible | Windows 2000 Professional [solo aplicaciones de escritorio] |
| Servidor mínimo compatible | Windows Server 2003 [solo aplicaciones de escritorio] |
| Plataforma de destino | Windows |
| Encabezado | winuser.h (incluir Windows.h) |
| Library | User32.lib |
| Archivo DLL | User32.dll |
| Redistribuible | RDK de accesibilidad activa 1.3 en Windows NT 4.0 con SP6 y versiones posteriores y Windows 95 |