Функция 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

Значения флагов, указывающие расположение функции перехватчика и событий, которые необходимо пропустить. Допустимы следующие флаги:

Значение Значение
WINEVENT_INCONTEXT
 Библиотека DLL, содержащая функцию обратного вызова, сопоставляется с адресным пространством процесса, создающего событие. С этим флагом система отправляет уведомления о событиях в функцию обратного вызова по мере их возникновения. Функция-перехватчик должна находиться в библиотеке DLL, если указан этот флаг. Этот флаг не действует, если вызывающий и генерирующий процессы не являются 32-разрядными или 64-разрядными процессами или когда процесс создания является консольным приложением. Дополнительные сведения см. в разделе Функции перехватчика в контексте.
WINEVENT_OUTOFCONTEXT
 Функция обратного вызова не сопоставляется с адресным пространством процесса, создающего событие. Так как функция-перехватчик вызывается через границы процесса, система должна ставить события в очередь. Хотя этот метод является асинхронным, события гарантированно будут находиться в последовательном порядке. Дополнительные сведения см. в разделе Вне контекстные функции перехватчика.
WINEVENT_SKIPOWNPROCESS
 Запрещает этому экземпляру перехватчика получать события, создаваемые потоками в этом процессе. Этот флаг не запрещает потокам создавать события.
WINEVENT_SKIPOWNTHREAD
 Запрещает этому экземпляру перехватчика получать события, созданные потоком, который регистрирует этот перехватчик.
 

Допустимы следующие сочетания флагов:

  • WINEVENT_INCONTEXT | WINEVENT_SKIPOWNPROCESS
  • WINEVENT_INCONTEXT | WINEVENT_SKIPOWNTHREAD
  • WINEVENT_OUTOFCONTEXT | WINEVENT_SKIPOWNPROCESS
  • WINEVENT_OUTOFCONTEXT | WINEVENT_SKIPOWNTHREAD
Кроме того, клиентские приложения могут указывать WINEVENT_INCONTEXT или WINEVENT_OUTOFCONTEXT отдельно.

Сведения о разработке приложений из Магазина 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

См. также раздел

Регистрация функции-перехватчика

UnhookWinEvent

WinEventProc