SetWindowsHookExA 함수(winuser.h)

아티클
08/28/2023

애플리케이션 정의 후크 프로시저를 후크 체인에 설치합니다. 후크 프로시저를 설치하여 특정 유형의 이벤트에 대해 시스템을 모니터링합니다. 이러한 이벤트는 특정 스레드 또는 호출 스레드와 동일한 데스크톱의 모든 스레드와 연결됩니다.

구문

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

매개 변수

[in] idHook

형식: int

설치할 후크 프로시저의 유형입니다. 이 매개 변수는 다음 값 중 하나일 수 있습니다.

값	의미
WH_CALLWNDPROC 4	시스템에서 대상 창 프로시저로 보내기 전에 메시지를 모니터링하는 후크 프로시저를 설치합니다. 자세한 내용은 CallWndProc 후크 프로시저를 참조하세요.
WH_CALLWNDPROCRET 12	대상 창 프로시저에서 처리된 후 메시지를 모니터링하는 후크 프로시저를 설치합니다. 자세한 내용은 [HOOKPROC 콜백 함수](nc-winuser-hookproc.md) 후크 프로시저를 참조하세요.
WH_CBT 5	CBT 애플리케이션에 유용한 알림을 수신하는 후크 프로시저를 설치합니다. 자세한 내용은 CBTProc 후크 프로시저를 참조하세요.
WH_DEBUG 9	다른 후크 프로시저를 디버깅하는 데 유용한 후크 프로시저를 설치합니다. 자세한 내용은 DebugProc 후크 프로시저를 참조하세요.
WH_FOREGROUNDIDLE 11	애플리케이션의 포그라운드 스레드가 유휴 상태가 될 때 호출되는 후크 프로시저를 설치합니다. 이 후크는 유휴 시간 동안 우선 순위가 낮은 작업을 수행하는 데 유용합니다. 자세한 내용은 ForegroundIdleProc 후크 프로시저를 참조하세요.
WH_GETMESSAGE 3	메시지 큐에 게시된 메시지를 모니터링하는 후크 프로시저를 설치합니다. 자세한 내용은 GetMsgProc 후크 프로시저를 참조하세요.
WH_JOURNALPLAYBACK 1	경고 Windows 11 이상: 저널링 후크 API는 지원되지 않습니다. 대신 SendInput TextInput API를 사용하는 것이 좋습니다. WH_JOURNALRECORD 후크 프로시저에서 이전에 기록한 메시지를 게시하는 후크 프로시저를 설치합니다. 자세한 내용은 JournalPlaybackProc 후크 프로시저를 참조하세요.
WH_JOURNALRECORD 0	경고 Windows 11 이상: 저널링 후크 API는 지원되지 않습니다. 대신 SendInput TextInput API를 사용하는 것이 좋습니다. 시스템 메시지 큐에 게시된 입력 메시지를 기록하는 후크 프로시저를 설치합니다. 이 후크는 매크로를 기록하는 데 유용합니다. 자세한 내용은 JournalRecordProc 후크 프로시저를 참조하세요.
WH_KEYBOARD 2	키 입력 메시지를 모니터링하는 후크 프로시저를 설치합니다. 자세한 내용은 KeyboardProc 후크 프로시저를 참조하세요.
WH_KEYBOARD_LL 13	하위 수준 키보드 입력 이벤트를 모니터링하는 후크 프로시저를 설치합니다. 자세한 내용은 [LowLevelKeyboardProc](/windows/win32/winmsg/lowlevelkeyboardproc) 후크 프로시저를 참조하세요.
WH_MOUSE 7	마우스 메시지를 모니터링하는 후크 프로시저를 설치합니다. 자세한 내용은 MouseProc 후크 프로시저를 참조하세요.
WH_MOUSE_LL 14	하위 수준 마우스 입력 이벤트를 모니터링하는 후크 프로시저를 설치합니다. 자세한 내용은 LowLevelMouseProc 후크 프로시저를 참조하세요.
WH_MSGFILTER -1	대화 상자, 메시지 상자, 메뉴 또는 스크롤 막대에서 입력 이벤트의 결과로 생성된 메시지를 모니터링하는 후크 프로시저를 설치합니다. 자세한 내용은 MessageProc 후크 프로시저를 참조하세요.
WH_SHELL 10	셸 애플리케이션에 유용한 알림을 수신하는 후크 프로시저를 설치합니다. 자세한 내용은 ShellProc 후크 프로시저를 참조하세요.
WH_SYSMSGFILTER 6	대화 상자, 메시지 상자, 메뉴 또는 스크롤 막대에서 입력 이벤트의 결과로 생성된 메시지를 모니터링하는 후크 프로시저를 설치합니다. 후크 프로시저는 호출 스레드와 동일한 데스크톱의 모든 애플리케이션에 대해 이러한 메시지를 모니터링합니다. 자세한 내용은 SysMsgProc 후크 프로시저를 참조하세요.

[in] lpfn

형식: HOOKPROC

후크 프로시저에 대한 포인터입니다. dwThreadId 매개 변수가 0이거나 다른 프로세스에서 만든 스레드의 식별자를 지정하는 경우 lpfn 매개 변수는 DLL의 후크 프로시저를 가리킵니다. 그렇지 않으면 lpfn은 현재 프로세스와 연결된 코드에서 후크 프로시저를 가리킬 수 있습니다.

[in] hmod

형식: HINSTANCE

lpfn 매개 변수가 가리키는 후크 프로시저를 포함하는 DLL에 대한 핸들입니다. dwThreadId 매개 변수가 현재 프로세스에서 만든 스레드를 지정하고 후크 프로시저가 현재 프로세스와 연결된 코드 내에 있는 경우 hMod 매개 변수를 NULL로 설정해야 합니다.

[in] dwThreadId

형식:DWORD

후크 프로시저를 연결할 스레드의 식별자입니다. 데스크톱 앱의 경우 이 매개 변수가 0이면 후크 프로시저가 호출 스레드와 동일한 데스크톱에서 실행되는 모든 기존 스레드와 연결됩니다. Windows 스토어 앱의 경우 주의 섹션을 참조하세요.

반환 값

형식: HHOOK

함수가 성공하면 반환 값은 후크 프로시저에 대한 핸들입니다.

함수가 실패하면 반환 값은 NULL입니다. 확장 오류 정보를 가져오려면 GetLastError를 호출합니다.

설명

SetWindowsHookEx 를 사용하여 DLL을 다른 프로세스에 삽입할 수 있습니다. 32비트 DLL은 64비트 프로세스에 삽입할 수 없으며 64비트 DLL은 32비트 프로세스에 삽입할 수 없습니다. 애플리케이션이 다른 프로세스에서 후크를 사용해야 하는 경우 32비트 애플리케이션이 SetWindowsHookEx 를 호출하여 32비트 DLL을 32비트 프로세스에 삽입하고 64비트 애플리케이션 호출 SetWindowsHookEx 를 호출하여 64비트 DLL을 64비트 프로세스에 삽입해야 합니다. 32비트 및 64비트 DLL의 이름은 서로 달라야 합니다.

후크는 애플리케이션의 컨텍스트에서 실행되므로 애플리케이션의 "비트 수"에 일치해야 합니다. 32비트 애플리케이션이 64비트 Windows에 전역 후크를 설치하는 경우 32비트 후크가 각 32비트 프로세스에 삽입됩니다(일반적인 보안 경계가 적용됨). 64비트 프로세스에서 스레드는 여전히 "후크됨"으로 표시됩니다. 그러나 32비트 애플리케이션은 후크 코드를 실행해야 하므로 시스템은 후킹 앱의 컨텍스트에서 후크를 실행합니다. 특히 SetWindowsHookEx를 호출한 스레드에서 즉, 후킹 애플리케이션은 메시지를 계속 펌핑해야 하거나 64비트 프로세스의 정상적인 작동을 차단할 수 있습니다.

64비트 애플리케이션이 64비트 Windows에 전역 후크를 설치하는 경우 64비트 후크는 각 64비트 프로세스에 삽입되고 모든 32비트 프로세스는 후킹 애플리케이션에 대한 콜백을 사용합니다.

64비트 Windows 설치의 데스크톱에 있는 모든 애플리케이션을 후크하려면 적절한 프로세스에서 각각 32비트 전역 후크와 64비트 글로벌 후크를 설치하고 정상적인 작동을 차단하지 않도록 후킹 애플리케이션에서 메시지를 계속 펌핑해야 합니다. 이미 32비트 전역 후킹 애플리케이션이 있고 각 애플리케이션의 컨텍스트에서 실행할 필요가 없는 경우 64비트 버전을 만들 필요가 없습니다.

hMod 매개 변수가 NULL이고 dwThreadId 매개 변수가 0이거나 다른 프로세스에서 만든 스레드의 식별자를 지정하는 경우 오류가 발생할 수 있습니다.

CallNextHookEx 함수를 호출하여 다음 후크 프로시저에 연결하는 것은 선택 사항이지만 권장됩니다. 그렇지 않으면 후크를 설치한 다른 애플리케이션은 후크 알림을 받지 않으며 결과적으로 잘못 동작할 수 있습니다. 다른 애플리케이션에서 알림을 볼 수 없도록 반드시 방지해야 하는 경우가 아니면 CallNextHookEx 를 호출해야 합니다.

종료하기 전에 애플리케이션은 UnhookWindowsHookEx 함수 함수를 호출하여 후크와 연결된 시스템 리소스를 해제해야 합니다.

후크의 scope 후크 유형에 따라 달라집니다. 일부 후크는 전역 scope만 설정할 수 있으며, 다른 후크는 다음 표와 같이 특정 스레드에 대해서만 설정할 수도 있습니다.

후크	범위
WH_CALLWNDPROC	스레드 또는 전역
WH_CALLWNDPROCRET	스레드 또는 전역
WH_CBT	스레드 또는 전역
WH_DEBUG	스레드 또는 전역
WH_FOREGROUNDIDLE	스레드 또는 전역
WH_GETMESSAGE	스레드 또는 전역
WH_JOURNALPLAYBACK	전역 전용
WH_JOURNALRECORD	전역 전용
WH_KEYBOARD	스레드 또는 전역
WH_KEYBOARD_LL	전역 전용
WH_MOUSE	스레드 또는 전역
WH_MOUSE_LL	전역 전용
WH_MSGFILTER	스레드 또는 전역
WH_SHELL	스레드 또는 전역
WH_SYSMSGFILTER	전역 전용

지정된 후크 형식의 경우 스레드 후크를 먼저 호출한 다음 전역 후크를 호출합니다. 후크를 처리하는 스레드가 아니라 후크를 설치한 스레드에서 WH_MOUSE, WH_KEYBOARD, WH_JOURNAL*, WH_SHELL 및 하위 수준 후크를 호출할 수 있습니다. 이러한 후크의 경우 32비트 후크가 후크 체인의 64비트 후크보다 앞서 있는 경우 32비트 후크와 64비트 후크가 모두 호출될 수 있습니다.

전역 후크는 공유 리소스이며, 이를 설치하면 호출 스레드와 동일한 데스크톱의 모든 애플리케이션에 영향을 줍니다. 모든 전역 후크 함수는 라이브러리에 있어야 합니다. 전역 후크는 특수 용도의 애플리케이션으로 제한되거나 애플리케이션 디버깅 중에 개발 지원으로 사용해야 합니다. 후크가 더 이상 필요하지 않은 라이브러리는 후크 프로시저를 제거해야 합니다.

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

WH_JOURNALPLAYBACK
WH_JOURNALRECORD
WH_KEYBOARD
WH_KEYBOARD_LL
WH_MOUSE
WH_MOUSE_LL

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

예제

예제는 후크 프로시저 설치 및 해제를 참조하세요.

참고

winuser.h 헤더는 SETWindowsHookEx를 유니코드 전처리기 상수의 정의에 따라 이 함수의 ANSI 또는 유니코드 버전을 자동으로 선택하는 별칭으로 정의합니다. 인코딩 중립 별칭을 인코딩 중립이 아닌 코드와 혼합하면 컴파일 또는 런타임 오류가 발생하는 불일치가 발생할 수 있습니다. 자세한 내용은 함수 프로토타입에 대한 규칙을 참조하세요.

요구 사항

요구 사항	값
지원되는 최소 클라이언트	Windows 2000 Professional[데스크톱 앱만]
지원되는 최소 서버	Windows 2000 Server[데스크톱 앱만]
대상 플랫폼	Windows
헤더	winuser.h(Windows.h 포함)
라이브러리	User32.lib
DLL	User32.dll
API 세트	ext-ms-win-ntuser-window-l1-1-0(Windows 8 도입)