ControlService 함수(winsvc.h)
제어 코드를 서비스로 보냅니다.
서비스를 중지할 때 추가 정보를 지정하려면 ControlServiceEx 함수를 사용합니다.
구문
BOOL ControlService(
[in] SC_HANDLE hService,
[in] DWORD dwControl,
[out] LPSERVICE_STATUS lpServiceStatus
);
매개 변수
[in] hService
서비스에 대한 핸들입니다. 이 핸들은 OpenService 또는 CreateService 함수에서 반환됩니다. 이 핸들에 필요한 액세스 권한 은 요청된 dwControl 코드에 따라 달라집니다.
[in] dwControl
이 매개 변수는 다음 컨트롤 코드 중 하나일 수 있습니다.
이 값은 다음 표에 설명된 대로 사용자 정의 컨트롤 코드일 수도 있습니다.
| 제어 코드 | 의미 |
|---|---|
|
서비스는 제어 코드와 연결된 작업을 정의합니다. 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를 호출합니다.
서비스 제어 관리자가 설정할 수 있는 오류 코드는 다음과 같습니다. 다른 오류 코드는 서비스 제어 관리자가 호출하는 레지스트리 함수에서 설정할 수 있습니다.
| 반환 코드 | 설명 |
|---|---|
|
핸들에 필요한 액세스 권한이 없습니다. |
|
다른 실행 중인 서비스가 종속되어 있기 때문에 서비스를 중지할 수 없습니다. |
|
CreateService 또는 OpenService를 사용하여 지정된 핸들을 가져오지 않았거나 핸들이 더 이상 유효하지 않습니다. |
|
요청된 제어 코드가 정의되지 않았습니다. |
|
요청한 제어 코드가 잘못되었거나 서비스에 사용할 수 없습니다. |
|
서비스 상태가 SERVICE_STOPPED, SERVICE_START_PENDING 또는SERVICE_STOP_PENDING 때문에 요청된 제어 코드를 서비스로 보낼 수 없습니다. |
|
서비스가 시작되지 않았습니다. |
|
서비스에 대한 프로세스가 시작되었지만 StartServiceCtrlDispatcher를 호출하지 않았거나 StartServiceCtrlDispatcher 라는 스레드가 제어 처리기 함수에서 차단될 수 있습니다. |
|
시스템이 종료되고 있습니다. |
설명
ControlService 함수는 SCM(서비스 제어 관리자)에 요청된 제어 코드를 서비스에 보내도록 요청합니다. SCM은 서비스에서 코드를 수락하도록 지정하고 컨트롤 코드를 보낼 수 있는 상태인 경우 코드를 보냅니다.
SCM은 서비스 제어 알림을 직렬 방식으로 처리합니다. 한 서비스가 서비스 제어 알림 처리를 완료할 때까지 기다린 후 다음 알림을 보냅니다. 이 때문에 제어 코드를 처리하는 서비스가 있는 경우 ControlService 호출이 30초 동안 차단됩니다. 시간 제한이 만료되면 사용 중인 서비스가 처리기 함수에서 아직 반환되지 않은 경우 ControlService 는 ERROR_SERVICE_REQUEST_TIMEOUT 함께 실패합니다.
서비스를 중지하고 시작하려면 이 작업을 수행할 수 있는 보안 설명자가 필요합니다. 기본 보안 설명자를 사용하면 LocalSystem 계정과 관리자 및 Power Users 그룹의 구성원이 서비스를 중지하고 시작할 수 있습니다. 서비스의 보안 설명자를 변경하려면 서비스에 대한 DACL 수정을 참조하세요.
QueryServiceStatusEx 함수는 dwCurrentState 및 dwControlsAccepted 멤버가 실행 중인 서비스에서 허용하는 현재 상태 및 컨트롤을 나타내는 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을 반환하고 GetLastError 는 ERROR_SERVICE_CANNOT_ACCEPT_CTRL 반환합니다.
- (c)
- 서비스가 활성 상태가 아니므로 ControlService 는 0을 반환하고 GetLastError 는 ERROR_SERVICE_NOT_ACTIVE 반환합니다.
예제
예를 들어 서비스 중지를 참조하세요.
요구 사항
| 요구 사항 | 값 |
|---|---|
| 지원되는 최소 클라이언트 | Windows XP [데스크톱 앱만 해당] |
| 지원되는 최소 서버 | Windows Server 2003 [데스크톱 앱만 해당] |
| 대상 플랫폼 | Windows |
| 헤더 | winsvc.h(Windows.h 포함) |
| 라이브러리 | AdvApi32.lib |
| DLL | AdvApi32.dll |