SetServiceStatus 함수(winsvc.h)

호출 서비스에 대한 서비스 제어 관리자의 상태 정보를 업데이트.

구문

BOOL SetServiceStatus(
  [in] SERVICE_STATUS_HANDLE hServiceStatus,
  [in] LPSERVICE_STATUS      lpServiceStatus
);

매개 변수

[in] hServiceStatus

현재 서비스의 상태 정보 구조에 대한 핸들입니다. 이 핸들은 RegisterServiceCtrlHandlerEx 함수에 의해 반환됩니다.

[in] lpServiceStatus

호출 서비스에 대한 최신 상태 정보를 포함하는 SERVICE_STATUS 구조체에 대한 포인터입니다.

반환 값

함수가 성공하면 반환 값이 0이 아닙니다.

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

서비스 제어 관리자가 다음 오류 코드를 설정할 수 있습니다. 다른 오류 코드는 서비스 제어 관리자가 호출하는 레지스트리 함수에서 설정할 수 있습니다.

반환 코드 설명
ERROR_INVALID_DATA
지정된 서비스 상태 구조가 잘못되었습니다.
ERROR_INVALID_HANDLE
지정한 핸들이 잘못되었습니다.

설명

ServiceMain 함수는 먼저 RegisterServiceCtrlHandlerEx 함수를 호출하여 서비스의 SERVICE_STATUS_HANDLE 가져옵니다. 그런 다음 , SetServiceStatus 함수를 즉시 호출하여 해당 상태가 SERVICE_START_PENDING 서비스 제어 관리자에게 알립니다. 초기화 중에 서비스는 업데이트된 상태를 제공하여 진행 중이지만 더 많은 시간이 필요하다는 것을 나타낼 수 있습니다. 일반적인 버그는 서비스가 기본 스레드가 초기화를 수행하도록 하는 반면, 별도의 스레드가 SetServiceStatus 를 계속 호출하여 서비스 제어 관리자가 중단된 것으로 표시하지 않도록 하는 것입니다. 그러나 주 스레드가 중단되면 작업자 스레드가 주 스레드가 진행 중이라는 보고를 계속하기 때문에 서비스가 무한 루프로 끝납니다.

제어 요청을 처리한 후 서비스 상태가 변경되면 서비스의 처리기 함수가 SetServiceStatus 를 호출하여 서비스 제어 관리자에게 새 상태를 보고해야 합니다. 서비스가 중지 또는 종료 제어를 처리하는 경우와 같이 상태가 변경되는 경우에만 이 작업을 수행해야 합니다. 또한 서비스는 서비스의 모든 스레드에서 언제든지 이 함수를 사용하여 복구 가능한 오류로 인해 서비스가 중지되어야 하는 경우와 같은 상태 변경 사항을 서비스 제어 관리자에게 알릴 수 있습니다.

서비스는 서비스 상태 핸들을 가져오기 위해 RegisterServiceCtrlHandlerEx 를 호출한 후에만 이 함수를 호출할 수 있습니다.

서비스에서 dwCurrentState 멤버가 SERVICE_STOPPED 설정되고 dwWin32ExitCode 멤버가 0이 아닌 값으로 설정된 SetServiceStatus를 호출하는 경우 시스템 이벤트 로그에 다음 항목이 기록됩니다.

   Event ID    = 7023
   Source      = Service Control Manager
   Type        = Error
   Description = <ServiceName> terminated with the following error:
                 <ExitCode>.

이 함수를 호출할 때 모범 사례는 다음과 같습니다.

  • 보류 중인 상태에 대한 유효한 확인 지점 및 대기 힌트 값이 있는지 확인하여 SERVICE_STATUS 구조의 모든 필드를 초기화합니다. 적절한 대기 힌트를 사용합니다.
  • 상태가 SERVICE_START_PENDING 또는 서비스가 중단될 수 있는 동안에는 컨트롤을 허용하도록 등록하지 마세요. 초기화가 완료되면 SERVICE_CONTROL_STOP 코드를 수락합니다.
  • 서비스가 보류 중인 시작, 중지, 일시 중지 또는 계속 작업과 관련된 작업을 진행하는 경우에만 검사점 및 대기 힌트 값을 사용하여 이 함수를 호출합니다. 그렇지 않으면 SCM에서 서비스가 중단되었는지 검색할 수 없습니다.
  • ServiceMain이 실패하는 경우 적절한 종료 코드로 중지된 상태를 입력합니다.
  • 상태가 SERVICE_STOPPED 경우 필요한 모든 정리를 수행하고 SetServiceStatus 를 한 번만 호출합니다. 이 함수는 SCM에 대한 LRPC 호출을 수행합니다. SERVICE_STOPPED 상태의 함수에 대한 첫 번째 호출은 RPC 컨텍스트 핸들을 닫고 후속 호출로 인해 프로세스가 충돌할 수 있습니다.
  • 서비스 프로세스를 언제든지 종료할 수 있으므로 SERVICE_STOPPED SetServiceStatus 를 호출한 후 추가 작업을 수행하지 마세요.

예제

예를 들어 ServiceMain 함수 작성을 참조하세요.

요구 사항

   
지원되는 최소 클라이언트 Windows XP [데스크톱 앱만 해당]
지원되는 최소 서버 Windows Server 2003 [데스크톱 앱만 해당]
대상 플랫폼 Windows
헤더 winsvc.h(Windows.h 포함)
라이브러리 Advapi32.lib
DLL Advapi32.dll

추가 정보

HandlerEx

RegisterServiceCtrlHandlerEx

SERVICE_STATUS

서비스 함수

ServiceMain

SetServiceBits