SetServiceStatus 함수(winsvc.h)

아티클
08/27/2023

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

구문

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를 계속 호출하여 서비스 제어 관리자가 중단된 것으로 표시하지 않도록 하는 것입니다. 그러나 기본 스레드가 중단되면 작업자 스레드가 계속 기본 스레드가 진행 중이라고 보고하기 때문에 서비스가 무한 루프로 시작됩니다.

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

서비스는 RegisterServiceCtrlHandlerEx를 호출한 후에만 이 함수를 호출하여 서비스 상태 핸들을 가져올 수 있습니다.

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

   Event ID    = 7023
   Source      = Service Control Manager
   Type        = Error
   Description = &lt;ServiceName&gt; terminated with the following error:
                 &lt;ExitCode&gt;.

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

보류 중인 상태에 대해 유효한 검사 지점 및 대기 힌트 값이 있는지 확인하여 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