LPHANDLER_FUNCTION 콜백 함수(winsvc.h)

아티클
08/27/2023

RegisterServiceCtrlHandler 함수와 함께 사용되는 애플리케이션 정의 콜백 함수입니다. 서비스 프로그램은 이를 특정 서비스의 제어 처리기 함수로 사용할 수 있습니다.

LPHANDLER_FUNCTION 형식은 이 함수에 대한 포인터를 정의합니다. 처리기는 애플리케이션 정의 이름의 자리 표시자입니다.

이 함수는 RegisterServiceCtrlHandlerEx 함수와 함께 사용되는 HandlerEx 컨트롤 처리기 함수로 대체되었습니다. 서비스는 두 컨트롤 처리기를 사용할 수 있지만 새 컨트롤 처리기는 사용자 정의 컨텍스트 데이터 및 추가 확장된 제어 코드를 지원합니다.

구문

LPHANDLER_FUNCTION LphandlerFunction;

void LphandlerFunction(
  DWORD dwControl
)
{...}

매개 변수

dwControl

반환 값

없음

설명

서비스가 시작되면 해당 ServiceMain 함수는 즉시 RegisterServiceCtrlHandler 함수를 호출하여 제어 요청을 처리하는 처리기 함수를 지정해야 합니다.

서비스 프로세스의 기본 스레드에 있는 컨트롤 디스패처는 서비스 제어 관리자로부터 제어 요청을 받을 때마다 지정된 서비스에 대한 제어 처리기 함수를 호출합니다. 제어 요청을 처리한 후 서비스 상태가 변경되어 새 상태 서비스 제어 관리자에 보고하는 경우 제어 처리기는 SetServiceStatus 함수를 호출해야 합니다.

컨트롤 처리기 함수는 알림을 받고 즉시 반환하기 위한 것입니다. 콜백 함수는 해당 매개 변수를 저장하고 다른 스레드를 만들어 추가 작업을 수행해야 합니다. (애플리케이션은 서비스를 중지하기 전에 이러한 스레드가 종료되었는지 확인해야 합니다.) 특히 컨트롤 처리기는 교착 상태가 발생하거나 시스템이 응답을 중지할 수 있으므로 잠금을 취하는 것과 같이 차단할 수 있는 작업을 피해야 합니다.

서비스 제어 관리자가 서비스에 제어 코드를 보내면 처리기 함수가 반환되기를 기다린 후 다른 서비스에 추가 제어 코드를 보냅니다. 컨트롤 처리기는 가능한 한 빨리 반환해야 합니다. 30초 이내에 반환되지 않으면 SCM에서 오류를 반환합니다. 서비스에서 제어 처리기를 실행할 때 서비스가 긴 처리를 수행해야 하는 경우 긴 처리를 수행하는 보조 스레드를 만든 다음 컨트롤 처리기에서 반환해야 합니다. 이렇게 하면 서비스가 컨트롤 디스패처를 연결하고 다른 서비스가 제어 코드를 수신하지 못하도록 차단할 수 있습니다.

SERVICE_CONTROL_SHUTDOWN 제어 코드는 서비스 종료에 사용할 수 있는 제한된 시간(약 20초)이 있기 때문에 종료 중에 절대적으로 클린 서비스에 의해서만 처리되어야 합니다. 이 시간이 만료되면 서비스 종료가 완료되었는지 여부에 관계없이 시스템 종료가 진행됩니다. 시스템이 종료 상태로 남아 있는 경우(다시 시작되거나 전원이 끄지 않음) 서비스가 계속 실행됩니다. 서비스가 SERVICE_CONTROL_SHUTDOWN 수락하도록 등록하는 경우 제어 코드를 처리하고 적시에 중지해야 합니다. 그렇지 않으면 시스템이 시스템 종료를 진행하기 전에 서비스 종료에 허용되는 전체 시간을 기다려야 하므로 서비스를 종료하는 데 필요한 시간이 늘어나게 될 수 있습니다.

서비스가 클린 데 더 많은 시간이 필요한 경우 서비스 컨트롤러가 서비스 종료가 완료되었다는 것을 시스템에 보고하기 전에 대기 시간을 알 수 있도록 대기 힌트와 함께 STOP_PENDING 상태 메시지를 보내야 합니다. 그러나 서비스가 종료를 중지하지 않도록 하기 위해 서비스 컨트롤러가 대기하는 기간에 제한이 있습니다. 서비스가 서비스 스냅인을 통해 종료되는 경우 제한은 125초입니다. 운영 체제가 다시 부팅되는 경우 시간 제한은 다음 레지스트리 키의 WaitToKillServiceTimeout 값에 지정됩니다.

HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control

서비스는 SetConsoleCtrlHandler 함수를 사용하여 종료 알림을 받을 수도 있습니다. 이 알림은 실행 중인 애플리케이션이 종료될 때 수신되며, 이는 서비스가 종료되기 전에 발생합니다.

예제

예제는 컨트롤 처리기 함수 작성을 참조하세요.

요구 사항

요구 사항	값
지원되는 최소 클라이언트	Windows XP [데스크톱 앱만 해당]
지원되는 최소 서버	Windows Server 2003 [데스크톱 앱만 해당]
대상 플랫폼	Windows
헤더	winsvc.h(Windows.h 포함)