Функция SetWinEventHook (winuser.h)
Задает функцию перехватчика событий для диапазона событий.
Синтаксис
HWINEVENTHOOK SetWinEventHook(
[in] DWORD eventMin,
[in] DWORD eventMax,
[in] HMODULE hmodWinEventProc,
[in] WINEVENTPROC pfnWinEventProc,
[in] DWORD idProcess,
[in] DWORD idThread,
[in] DWORD dwFlags
);
Параметры
[in] eventMin
Тип: UINT
Задает константу события для наименьшего значения события в диапазоне событий, обрабатываемых функцией-перехватчиком. Для этого параметра можно задать значение EVENT_MIN , чтобы указать минимально возможное значение события.
[in] eventMax
Тип: UINT
Задает константу события для наибольшего значения события в диапазоне событий, обрабатываемых функцией-перехватчиком. Для этого параметра можно задать значение EVENT_MAX , чтобы указать максимально возможное значение события.
[in] hmodWinEventProc
Тип: HMODULE
Выполните обработку библиотеки DLL, содержащей функцию перехватчика в lpfnWinEventProc, если флаг WINEVENT_INCONTEXT указан в параметре dwFlags . Если функция перехватчика не находится в библиотеке DLL или если указан флаг WINEVENT_OUTOFCONTEXT, этот параметр имеет значение NULL.
[in] pfnWinEventProc
Тип: WINEVENTPROC
Указатель на функцию перехватчика событий. Дополнительные сведения об этой функции см. в разделе WinEventProc.
[in] idProcess
Тип: DWORD
Указывает идентификатор процесса, из которого функция-перехватчик получает события. Укажите ноль (0) для получения событий от всех процессов на текущем рабочем столе.
[in] idThread
Тип: DWORD
Указывает идентификатор потока, из которого функция-перехватчик получает события. Если этот параметр равен нулю, функция перехватчика связывается со всеми существующими потоками на текущем рабочем столе.
[in] dwFlags
Тип: UINT
Значения флагов, указывающие расположение функции перехватчика и событий, которые необходимо пропустить. Допустимы следующие флаги:
| Значение | Значение |
|---|---|
|
Библиотека DLL, содержащая функцию обратного вызова, сопоставляется с адресным пространством процесса, создающего событие. С этим флагом система отправляет уведомления о событиях в функцию обратного вызова по мере их возникновения. Функция-перехватчик должна находиться в библиотеке DLL, если указан этот флаг. Этот флаг не действует, если вызывающий и генерирующий процессы не являются 32-разрядными или 64-разрядными процессами или когда процесс создания является консольным приложением. Дополнительные сведения см. в разделе Функции перехватчика в контексте. |
|
Функция обратного вызова не сопоставляется с адресным пространством процесса, создающего событие. Так как функция-перехватчик вызывается через границы процесса, система должна ставить события в очередь. Хотя этот метод является асинхронным, события гарантированно будут находиться в последовательном порядке. Дополнительные сведения см. в разделе Вне контекстные функции перехватчика. |
|
Запрещает этому экземпляру перехватчика получать события, создаваемые потоками в этом процессе. Этот флаг не запрещает потокам создавать события. |
|
Запрещает этому экземпляру перехватчика получать события, созданные потоком, который регистрирует этот перехватчик. |
Допустимы следующие сочетания флагов:
- WINEVENT_INCONTEXT | WINEVENT_SKIPOWNPROCESS
- WINEVENT_INCONTEXT | WINEVENT_SKIPOWNTHREAD
- WINEVENT_OUTOFCONTEXT | WINEVENT_SKIPOWNPROCESS
- WINEVENT_OUTOFCONTEXT | WINEVENT_SKIPOWNTHREAD
Сведения о разработке приложений из Магазина Windows см. в разделе "Примечания".
Возвращаемое значение
Тип: HWINEVENTHOOK
В случае успешного выполнения возвращает значение HWINEVENTHOOK , которое идентифицирует этот экземпляр перехватчика событий. Приложения сохраняют это возвращаемое значение, чтобы использовать его с функцией UnhookWinEvent .
В случае неудачи возвращает ноль.
Комментарии
Эта функция позволяет клиентам указать, какие процессы и потоки их интересуют.
Если параметр idProcess не равен нулю, а idThread равен нулю, функция перехватчика получает указанные события из всех потоков в этом процессе. Если параметр idProcess равен нулю, а idThread — ненулевому, функция перехватчика получает указанные события только из потока, заданного idThread. Если оба значения равны нулю, функция-перехватчик получает указанные события из всех потоков и процессов.
Клиенты могут вызывать SetWinEventHook несколько раз, если они хотят зарегистрировать дополнительные функции перехватчика или прослушивать дополнительные события.
Клиентский поток, вызывающий SetWinEventHook , должен иметь цикл сообщений для получения событий.
При использовании SetWinEventHook для задания обратного вызова в управляемом коде следует использовать структуру GCHandle , чтобы избежать исключений. Это указывает сборщику мусора не перемещать обратный вызов.
Для событий вне контекста событие доставляется в том же потоке, который называется SetWinEventHook. В некоторых ситуациях, даже если вы запрашиваете события WINEVENT_INCONTEXT, события по-прежнему будут доставляться вне контекста. Эти сценарии включают события из окон консоли и события процессов, которые имеют разную битовую глубину (64 и 32 бита), чем вызывающий объект.
Пока функция перехватчика обрабатывает событие, могут быть активированы дополнительные события, что может привести к повторному вхождать функцию перехватчика до завершения обработки исходного события. Проблема повторного входа в функциях-перехватчиках заключается в том, что события завершаются вне последовательности, если только функция перехватчика не обрабатывает эту ситуацию. Дополнительные сведения см. в разделе Защита от повторного входа.
Разработка приложений для Магазина Windows Если dwFlags WINEVENT_INCONTEXT AND (idProcess = 0 | idThread = 0), то библиотеки DLL-обработчиков окон не загружаются внутри процесса для процессов приложений Магазина Windows и брокера среда выполнения Windows, если они не установлены процессами UIAccess (средствами специальных возможностей). Уведомление доставляется в потоке установщика.
Это поведение аналогично тому, что происходит при несоответствии архитектуры между библиотекой DLL перехватчика и процессом целевого приложения, например, если библиотека DLL-обработчика является 32-разрядной, а процесс приложения — 64-разрядным.
Примеры
В следующем примере кода показано, как клиентское приложение может прослушивать события menu-start и menu-end. Для простоты обработчик событий просто отправляет некоторые сведения в стандартные выходные данные.
// 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();
}
}
Требования
| Требование | Значение |
|---|---|
| Минимальная версия клиента | Windows 2000 Professional [только классические приложения] |
| Минимальная версия сервера | Windows Server 2003 [только классические приложения] |
| Целевая платформа | Windows |
| Header | winuser.h (включая Windows.h) |
| Библиотека | User32.lib |
| DLL | User32.dll |
| Распространяемые компоненты | Активные специальные возможности 1.3 RDK в Windows NT 4.0 с пакетом обновления 6 (SP6) и более поздних версий и Windows 95 |
См. также раздел
Обратная связь
Ожидается в ближайшее время: в течение 2024 года мы постепенно откажемся от GitHub Issues как механизма обратной связи для контента и заменим его новой системой обратной связи. Дополнительные сведения см. в разделе https://aka.ms/ContentUserFeedback.
Отправить и просмотреть отзыв по