다음을 통해 공유


ControlService 함수(winsvc.h)

제어 코드를 서비스로 보냅니다.

서비스를 중지할 때 추가 정보를 지정하려면 ControlServiceEx 함수를 사용합니다.

구문

BOOL ControlService(
  [in]  SC_HANDLE        hService,
  [in]  DWORD            dwControl,
  [out] LPSERVICE_STATUS lpServiceStatus
);

매개 변수

[in] hService

서비스에 대한 핸들입니다. 이 핸들은 OpenService 또는 CreateService 함수에서 반환됩니다. 이 핸들에 필요한 액세스 권한 은 요청된 dwControl 코드에 따라 달라집니다.

[in] dwControl

이 매개 변수는 다음 컨트롤 코드 중 하나일 수 있습니다.

제어 코드 의미
SERVICE_CONTROL_CONTINUE
0x00000003
일시 중지된 서비스에 다시 시작해야 한다는 것을 알 수 있습니다. hService 핸들에는 SERVICE_PAUSE_CONTINUE 액세스 권한이 있어야 합니다.
SERVICE_CONTROL_INTERROGATE
0x00000004
서비스에 현재 상태 정보를 서비스 제어 관리자에 보고해야 한다고 알 수 있습니다. hService 핸들에는 SERVICE_INTERROGATE 액세스 권한이 있어야 합니다.

SCM이 서비스의 현재 상태를 인식하기 때문에 이 컨트롤은 일반적으로 유용하지 않습니다.

SERVICE_CONTROL_NETBINDADD
0x00000007
네트워크 서비스에 바인딩을 위한 새 구성 요소가 있음을 알 수 있습니다. hService 핸들에는 SERVICE_PAUSE_CONTINUE 액세스 권한이 있어야 합니다. 그러나 이 제어 코드는 더 이상 사용되지 않습니다. 대신 플러그 앤 플레이 기능을 사용합니다.
SERVICE_CONTROL_NETBINDDISABLE
0x0000000a
네트워크 서비스에 바인딩 중 하나가 비활성화되었음을 알 수 있습니다. hService 핸들에는 SERVICE_PAUSE_CONTINUE 액세스 권한이 있어야 합니다. 그러나 이 제어 코드는 더 이상 사용되지 않습니다. 대신 플러그 앤 플레이 기능을 사용합니다.
SERVICE_CONTROL_NETBINDENABLE
0x00000009
비활성화된 바인딩이 사용하도록 설정되었음을 네트워크 서비스에 알 수 있습니다. hService 핸들에는 SERVICE_PAUSE_CONTINUE 액세스 권한이 있어야 합니다. 그러나 이 제어 코드는 더 이상 사용되지 않습니다. 대신 플러그 앤 플레이 기능을 사용합니다.
SERVICE_CONTROL_NETBINDREMOVE
0x00000008
네트워크 서비스에 바인딩 구성 요소가 제거되었음을 알 수 있습니다. hService 핸들에는 SERVICE_PAUSE_CONTINUE 액세스 권한이 있어야 합니다. 그러나 이 제어 코드는 더 이상 사용되지 않습니다. 대신 플러그 앤 플레이 기능을 사용합니다.
SERVICE_CONTROL_PARAMCHANGE
0x00000006
서비스에 시작 매개 변수가 변경되었다는 것을 알 수 있습니다. hService 핸들에는 SERVICE_PAUSE_CONTINUE 액세스 권한이 있어야 합니다.
SERVICE_CONTROL_PAUSE
0x00000002
일시 중지해야 한다는 것을 서비스에 알 수 있습니다. hService 핸들에는 SERVICE_PAUSE_CONTINUE 액세스 권한이 있어야 합니다.
SERVICE_CONTROL_STOP
0x00000001
중지해야 한다는 것을 서비스에 알 수 있습니다. hService 핸들에는 SERVICE_STOP 액세스 권한이 있어야 합니다.

서비스에 중지 요청을 보낸 후에는 다른 컨트롤을 서비스에 보내면 안 됩니다.

 

이 값은 다음 표에 설명된 대로 사용자 정의 컨트롤 코드일 수도 있습니다.

제어 코드 의미
범위 128 ~255
서비스는 제어 코드와 연결된 작업을 정의합니다. hService 핸들에는 SERVICE_USER_DEFINED_CONTROL 액세스 권한이 있어야 합니다.

[out] lpServiceStatus

최신 서비스 상태 정보를 수신하는 SERVICE_STATUS 구조체에 대한 포인터입니다. 반환되는 정보는 서비스가 서비스 제어 관리자에게 보고한 가장 최근의 상태 반영합니다.

서비스 제어 관리자는 GetLastError가 NO_ERROR,ERROR_INVALID_SERVICE_CONTROL, ERROR_SERVICE_CANNOT_ACCEPT_CTRL또는 ERROR_SERVICE_NOT_ACTIVE 오류 코드 중 하나를 반환하는 경우에만 구조를 채웁니다. 그렇지 않으면 구조체가 채워지지 않습니다.

반환 값

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

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

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

반환 코드 설명
ERROR_ACCESS_DENIED
핸들에 필요한 액세스 권한이 없습니다.
ERROR_DEPENDENT_SERVICES_RUNNING
다른 실행 중인 서비스가 종속되어 있기 때문에 서비스를 중지할 수 없습니다.
ERROR_INVALID_HANDLE
CreateService 또는 OpenService를 사용하여 지정된 핸들을 가져오지 않았거나 핸들이 더 이상 유효하지 않습니다.
ERROR_INVALID_PARAMETER
요청된 제어 코드가 정의되지 않았습니다.
ERROR_INVALID_SERVICE_CONTROL
요청한 제어 코드가 잘못되었거나 서비스에 사용할 수 없습니다.
ERROR_SERVICE_CANNOT_ACCEPT_CTRL
서비스 상태가 SERVICE_STOPPED, SERVICE_START_PENDING 또는SERVICE_STOP_PENDING 때문에 요청된 제어 코드를 서비스로 보낼 수 없습니다.
ERROR_SERVICE_NOT_ACTIVE
서비스가 시작되지 않았습니다.
ERROR_SERVICE_REQUEST_TIMEOUT
서비스에 대한 프로세스가 시작되었지만 StartServiceCtrlDispatcher를 호출하지 않았거나 StartServiceCtrlDispatcher 라는 스레드가 제어 처리기 함수에서 차단될 수 있습니다.
ERROR_SHUTDOWN_IN_PROGRESS
시스템이 종료되고 있습니다.

설명

ControlService 함수는 SCM(서비스 제어 관리자)에 요청된 제어 코드를 서비스에 보내도록 요청합니다. SCM은 서비스에서 코드를 수락하도록 지정하고 컨트롤 코드를 보낼 수 있는 상태인 경우 코드를 보냅니다.

SCM은 서비스 제어 알림을 직렬 방식으로 처리합니다. 한 서비스가 서비스 제어 알림 처리를 완료할 때까지 기다린 후 다음 알림을 보냅니다. 이 때문에 제어 코드를 처리하는 서비스가 있는 경우 ControlService 호출이 30초 동안 차단됩니다. 시간 제한이 만료되면 사용 중인 서비스가 처리기 함수에서 아직 반환되지 않은 경우 ControlServiceERROR_SERVICE_REQUEST_TIMEOUT 함께 실패합니다.

서비스를 중지하고 시작하려면 이 작업을 수행할 수 있는 보안 설명자가 필요합니다. 기본 보안 설명자를 사용하면 LocalSystem 계정과 관리자 및 Power Users 그룹의 구성원이 서비스를 중지하고 시작할 수 있습니다. 서비스의 보안 설명자를 변경하려면 서비스에 대한 DACL 수정을 참조하세요.

QueryServiceStatusEx 함수는 dwCurrentStatedwControlsAccepted 멤버가 실행 중인 서비스에서 허용하는 현재 상태 및 컨트롤을 나타내는 SERVICE_STATUS_PROCESS 구조를 반환합니다. 실행 중인 모든 서비스는 기본적으로 SERVICE_CONTROL_INTERROGATE 제어 코드를 허용합니다. 드라이버는 SERVICE_CONTROL_STOP SERVICE_CONTROL_INTERROGATE 이외의 제어 코드를 허용하지 않습니다. 각 서비스는 SetServiceStatus 함수를 호출하여 상태 보고할 때 허용하는 다른 컨트롤 코드를 지정합니다. 서비스는 실행 중일 때 어떤 작업을 수행하든 항상 이러한 코드를 수락해야 합니다.

다음 표에서는 가능한 각 서비스 상태에서 SCM의 동작을 보여 드립니다.

서비스 상태 Stop 기타 컨트롤
STOPPED (c) (c)
STOP_PENDING (b) (b)
START_PENDING (a) (b)
실행 (a) (a)
CONTINUE_PENDING (a) (a)
PAUSE_PENDING (a) (a)
일시 중지 (a) (a)
(a)
서비스에서 이 제어 코드를 수락하면 서비스에 요청을 보냅니다. 그렇지 않으면 ControlService 는 0을 반환하고 GetLastError는ERROR_INVALID_SERVICE_CONTROL 반환합니다.
(b)
서비스가 컨트롤을 보낼 수 있는 상태가 아니므로 ControlService 는 0을 반환하고 GetLastErrorERROR_SERVICE_CANNOT_ACCEPT_CTRL 반환합니다.
(c)
서비스가 활성 상태가 아니므로 ControlService 는 0을 반환하고 GetLastErrorERROR_SERVICE_NOT_ACTIVE 반환합니다.

예제

예를 들어 서비스 중지를 참조하세요.

요구 사항

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

추가 정보

ControlServiceEx

CreateService

OpenService

QueryServiceStatusEx

SERVICE_STATUS

서비스 제어 요청

서비스 함수

SetServiceObjectSecurity

SetServiceStatus