SetWinEventHook 함수(winuser.h)

아티클
03/13/2024

이벤트 범위에 대한 이벤트 후크 함수를 설정합니다.

구문

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

dwFlags 매개 변수에 WINEVENT_INCONTEXT 플래그가 지정된 경우 lpfnWinEventProc의 후크 함수를 포함하는 DLL에 대한 핸들입니다. 후크 함수가 DLL에 없거나 WINEVENT_OUTOFCONTEXT 플래그가 지정된 경우 이 매개 변수는 NULL입니다.

[in] pfnWinEventProc

형식: WINEVENTPROC

이벤트 후크 함수에 대한 포인터입니다. 이 함수에 대한 자세한 내용은 WinEventProc을 참조하세요.

[in] idProcess

형식: DWORD

후크 함수가 이벤트를 수신하는 프로세스의 ID를 지정합니다. 현재 데스크톱의 모든 프로세스에서 이벤트를 수신하려면 0을 지정합니다.

[in] idThread

형식: DWORD

후크 함수가 이벤트를 수신하는 스레드의 ID를 지정합니다. 이 매개 변수가 0이면 후크 함수가 현재 데스크톱의 모든 기존 스레드와 연결됩니다.

[in] dwFlags

형식: UINT

후크 함수의 위치와 건너뛸 이벤트의 위치를 지정하는 플래그 값입니다. 유효한 플래그는 다음과 같습니다.

값	의미
WINEVENT_INCONTEXT	콜백 함수를 포함하는 DLL은 이벤트를 생성하는 프로세스의 주소 공간에 매핑됩니다. 이 플래그를 사용하면 시스템에서 이벤트 알림이 발생하는 콜백 함수로 보냅니다. 이 플래그를 지정할 때 후크 함수는 DLL에 있어야 합니다. 호출 프로세스와 생성 프로세스가 모두 32비트 또는 64비트 프로세스가 아니거나 생성 프로세스가 콘솔 애플리케이션인 경우 이 플래그는 영향을 주지 않습니다. 자세한 내용은 컨텍스트 내 후크 함수를 참조하세요.
WINEVENT_OUTOFCONTEXT	콜백 함수는 이벤트를 생성하는 프로세스의 주소 공간에 매핑되지 않습니다. 후크 함수는 프로세스 경계를 넘어 호출되므로 시스템은 이벤트를 큐에 추가해야 합니다. 이 메서드는 비동기적이지만 이벤트는 순차적으로 유지됩니다. 자세한 내용은 컨텍스트 외 후크 함수를 참조하세요.
WINEVENT_SKIPOWNPROCESS	후크의 이 instance 이 프로세스에서 스레드에 의해 생성된 이벤트를 수신하지 못하도록 합니다. 이 플래그는 스레드가 이벤트를 생성하는 것을 방지하지 않습니다.
WINEVENT_SKIPOWNTHREAD	후크의 이 instance 이 후크를 등록하는 스레드에서 생성된 이벤트를 수신하지 못하도록 합니다.

다음과 같은 플래그 조합이 유효합니다.

WINEVENT_INCONTEXT | WINEVENT_SKIPOWNPROCESS
WINEVENT_INCONTEXT | WINEVENT_SKIPOWNTHREAD
WINEVENT_OUTOFCONTEXT | WINEVENT_SKIPOWNPROCESS
WINEVENT_OUTOFCONTEXT | WINEVENT_SKIPOWNTHREAD

또한 클라이언트 애플리케이션은 WINEVENT_INCONTEXT 또는 WINEVENT_OUTOFCONTEXT 단독으로 지정할 수 있습니다.

Windows 스토어 앱 개발에 대한 자세한 내용은 설명 섹션을 참조하세요.

반환 값

형식: HWINEVENTHOOK

성공하면 이 이벤트 후크 instance 식별하는 HWINEVENTHOOK 값을 반환합니다. 애플리케이션은 이 반환 값을 저장하여 UnhookWinEvent 함수와 함께 사용합니다.

실패하면 는 0을 반환합니다.

설명

이 함수를 사용하면 클라이언트가 관심 있는 프로세스와 스레드를 지정할 수 있습니다.

idProcess 매개 변수가 0이 아니고 idThread가 0이면 후크 함수는 해당 프로세스의 모든 스레드에서 지정된 이벤트를 받습니다. idProcess 매개 변수가 0이고 idThread가 0이 아니면 후크 함수는 idThread로 지정된 스레드에서만 지정된 이벤트를 받습니다. 둘 다 0이면 후크 함수는 모든 스레드 및 프로세스에서 지정된 이벤트를 수신합니다.

클라이언트는 추가 후크 함수를 등록하거나 추가 이벤트를 수신 대기하려는 경우 SetWinEventHook 을 여러 번 호출할 수 있습니다.

SetWinEventHook를 호출하는 클라이언트 스레드는 이벤트를 수신하기 위해 메시지 루프가 있어야 합니다.

SetWinEventHook를 사용하여 관리 코드에서 콜백을 설정하는 경우 GCHandle 구조를 사용하여 예외를 방지해야 합니다. 그러면 가비지 수집기에서 콜백을 이동하지 않도록 지시합니다.

컨텍스트가 다른 이벤트의 경우 이벤트는 SetWinEventHook라는 동일한 스레드에서 전달됩니다. 경우에 따라 WINEVENT_INCONTEXT 이벤트를 요청하더라도 이벤트는 컨텍스트 외부로 전달됩니다. 이러한 시나리오에는 콘솔 창의 이벤트와 호출자와 다른 비트 깊이(64비트 및 32비트)가 있는 프로세스의 이벤트가 포함됩니다.

후크 함수가 이벤트를 처리하는 동안 추가 이벤트가 트리거되어 원래 이벤트에 대한 처리가 완료되기 전에 후크 함수가 다시 입력될 수 있습니다. 후크 함수의 재진입 문제는 후크 함수가 이 상황을 처리하지 않는 한 이벤트가 시퀀스에서 완료된다는 것입니다. 자세한 내용은 재입력에 대한 보호 를 참조하세요.

Windows 스토어 앱 개발 dwFlags가 WINEVENT_INCONTEXT AND(idProcess = 0 | idThread = 0)인 경우 UIAccess 프로세스(접근성 도구)에서 설치하지 않는 한 Windows 스토어 앱 프로세스 및 Windows 런타임 broker 프로세스에 대해 창 후크 DLL이 in-process로 로드되지 않습니다. 알림은 설치 관리자의 스레드에서 전달됩니다.

이 동작은 후크 DLL과 대상 애플리케이션 프로세스 간에 아키텍처 불일치가 있는 경우(예: 후크 DLL이 32비트이고 애플리케이션 프로세스가 64비트인 경우)와 유사합니다.

예제

다음 예제 코드는 클라이언트 애플리케이션이 메뉴 시작 및 메뉴 끝 이벤트를 수신 대기하는 방법을 보여 줍니다. 간단히 하기 위해 이벤트 처리기는 표준 출력에 일부 정보를 보냅니다.


// 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
헤더	winuser.h(Windows.h 포함)
라이브러리	User32.lib
DLL	User32.dll
재배포 가능 파일	SP6 이상 및 Windows 95를 Windows NT 4.0의 활성 접근성 1.3 RDK

추가 정보

후크 함수 등록

UnhookWinEvent

WinEventProc

SetWinEventHook 함수(winuser.h)

구문

매개 변수

반환 값

설명

예제

요구 사항

추가 정보

피드백

피드백

추가 리소스