HandlerRoutine 콜백 함수

아티클
10/23/2023

SetConsoleCtrlHandler 함수와 함께 사용되는 애플리케이션 정의 함수입니다 . 콘솔 프로세스는 이 함수를 사용하여 프로세스에서 수신한 제어 신호를 처리합니다. 신호를 받으면 시스템에서 함수를 실행하는 프로세스에 새 스레드를 만듭니다.

PHANDLER_ROUTINE 형식은 이 콜백 함수에 대한 포인터를 정의합니다. HandlerRoutine 은 애플리케이션 정의 함수 이름의 자리 표시자입니다.

구문

BOOL WINAPI HandlerRoutine(
  _In_ DWORD dwCtrlType
);

매개 변수

dwCtrlType [in]
처리기에서 수신한 제어 신호의 형식입니다. 이 매개 변수는 다음 값 중 하나일 수 있습니다.

값	의미
CTRL_C_EVENT 0	`Ctrl+C` 신호는 키보드 입력 또는 GenerateConsoleCtrlEvent 함수에 의해 생성된 신호에서 수신되었습니다.
CTRL_BREAK_EVENT 1	`Ctrl+BREAK` 신호가 키보드 입력 또는 GenerateConsoleCtrlEvent에서 생성된 신호로부터 수신되었습니다.
CTRL_CLOSE_EVENT 2	사용자가 콘솔을 닫을 때(콘솔 창의 창 메뉴에서 닫기를 클릭하거나 작업 관리자에서 작업 종료 단추 명령을 클릭하여) 콘솔에 연결된 모든 프로세스에 시스템이 전송하는 신호입니다.
CTRL_LOGOFF_EVENT 5	사용자가 로그오프할 때 시스템이 모든 콘솔 프로세스에 보내는 신호입니다. 이 신호는 어떤 사용자가 로그오프 중인지를 나타내지 않으므로 가정을 할 수 없습니다. 이 신호는 서비스에서만 수신됩니다. 대화형 애플리케이션은 로그오프 시 종료되므로 시스템에서 이 신호를 보낼 때 존재하지 않습니다.
CTRL_SHUTDOWN_EVENT 6	시스템이 종료되면 시스템이 보내는 신호입니다. 대화형 애플리케이션은 시스템에서 이 신호를 보낼 때까지 존재하지 않으므로 이 상황에서는 서비스만 수신할 수 있습니다. 서비스에는 종료 이벤트에 대한 자체 알림 메커니즘도 있습니다. 자세한 내용은 처리기를 참조 하세요.

반환 값

함수가 컨트롤 신호를 처리하는 경우 TRUE를 반환해야 합니다. FALSE를 반환하는 경우 이 프로세스에 대한 처리기 목록의 다음 처리기 함수가 사용됩니다.

설명

시스템에서 처리기 함수를 실행하는 프로세스에서 새 스레드를 만들기 때문에 처리기 함수가 프로세스의 다른 스레드에 의해 종료될 수 있습니다. 프로세스의 스레드를 처리기 함수의 스레드와 동기화해야 합니다.

각 콘솔 프로세스에는 고유한 HandlerRoutine 함수 목록이 있습니다. 처음에 이 목록에는 ExitProcess를 호출 하는 기본 처리기 함수만 포함됩니다. 콘솔 프로세스는 다른 프로세스의 처리기 함수 목록에 영향을 주지 않는 SetConsoleCtrlHandler 함수를 호출하여 추가 처리기 함수를 추가하거나 제거합니다. 콘솔 프로세스에서 제어 신호를 받으면 처리기 중 하나가 TRUE를 반환할 때까지 해당 처리기 함수가 마지막으로 등록된 첫 번째 호출 기준으로 호출됩니다. 처리기가 TRUE를 반환하지 않으면 기본 처리기가 호출됩니다.

CTRL_CLOSE_EVENT, CTRL_LOGOFF_EVENT 및 CTRL_SHUTDOWN_EVENT 신호는 프로세스가 종료되기 전에 클린 수 있는 기회를 제공합니다. HandlerRoutine은 필요한 클린 다음 작업 중 하나를 수행할 수 있습니다.

ExitProcess 함수를 호출하여 프로세스를 종료합니다.
FALSE를 반환 합니다. 등록된 처리기 함수 중 TRUE를 반환하지 않으면 기본 처리기가 프로세스를 종료합니다.
TRUE를 반환 합니다. 이 경우 다른 처리기 함수가 호출되지 않고 시스템이 프로세스를 종료합니다.

프로세스는 SetProcessShutdownParameters 함수를 사용하여 시스템이 로그오프 또는 종료 중에 사용자에게 대화 상자를 표시하지 못하도록 할 수 있습니다. 이 경우 System은 HandlerRoutine이 TRUE를 반환하거나 제한 시간이 경과할 때 프로세스를 종료합니다.

콘솔 애플리케이션이 서비스로 실행되면 수정된 기본 콘솔 제어 처리기를 받습니다. 이 수정된 처리기는 CTRL_LOGOFF_EVENT 및 CTRL_SHUTDOWN_EVENT 신호를 처리할 때 ExitProcess를 호출하지 않습니다. 이렇게 하면 사용자가 로그오프한 후에도 서비스를 계속 실행할 수 있습니다. 서비스에서 자체 콘솔 제어 처리기를 설치하는 경우 이 처리기는 기본 처리기 전에 호출됩니다. CTRL_LOGOFF_EVENT 신호를 처리할 때 설치된 처리기가 ExitProcess를 호출하면 사용자가 로그오프할 때 서비스가 종료됩니다.

타사 라이브러리 또는 DLL은 애플리케이션에 대한 콘솔 제어 처리기를 설치할 수 있습니다. 이 경우 이 처리기는 기본 처리기를 재정의하고 사용자가 로그오프할 때 애플리케이션이 종료될 수 있습니다.

시간 제한

이벤트	상황	시간 제한
`CTRL_CLOSE_EVENT`	any	시스템 매개 변수 `SPI_GETHUNGAPPTIMEOUT`, 5000ms
`CTRL_LOGOFF_EVENT`	quick[1]	레지스트리 키 `CriticalAppShutdownTimeout` 또는 500ms
`CTRL_LOGOFF_EVENT`	위 항목 없음	시스템 매개 변수 `SPI_GETWAITTOKILLTIMEOUT`, 5000ms
`CTRL_SHUTDOWN_EVENT`	서비스 프로세스	시스템 매개 변수 `SPI_GETWAITTOKILLSERVICETIMEOUT`, 20000ms
`CTRL_SHUTDOWN_EVENT`	quick[1]	레지스트리 키 `CriticalAppShutdownTimeout` 또는 500ms
`CTRL_SHUTDOWN_EVENT`	위 항목 없음	시스템 매개 변수 `SPI_GETWAITTOKILLTIMEOUT`, 5000ms
`CTRL_C`, `CTRL_BREAK`	any	시간 제한 없음

[1]: "빠른" 이벤트는 사용되지 않지만 이를 지원하는 코드는 여전히 있습니다.

요구 사항


지원되는 최소 클라이언트	Windows 2000 Professional[데스크톱 앱만]
지원되는 최소 서버	Windows 2000 Server[데스크톱 앱만]
헤더	ConsoleApi.h(WinCon.h를 통해, Windows.h 포함)