ControlServiceExA 함수(winsvc.h)
제어 코드를 서비스로 보냅니다.
구문
BOOL ControlServiceExA(
[in] SC_HANDLE hService,
[in] DWORD dwControl,
[in] DWORD dwInfoLevel,
[in, out] PVOID pControlParams
);
매개 변수
[in] hService
서비스에 대한 핸들입니다. 이 핸들은 OpenService 또는 CreateService 함수에서 반환됩니다. 이 핸들에 필요한 액세스 권한 은 요청된 dwControl 코드에 따라 달라집니다.
[in] dwControl
이 매개 변수는 다음 컨트롤 코드 중 하나일 수 있습니다.
이 매개 변수는 다음 표에 설명된 대로 사용자 정의 제어 코드일 수도 있습니다.
| 제어 코드 | 의미 |
|---|---|
|
서비스는 제어 코드와 연결된 작업을 정의합니다. hService 핸들에는 SERVICE_USER_DEFINED_CONTROL 액세스 권한이 있어야 합니다. |
[in] dwInfoLevel
서비스 제어 매개 변수의 정보 수준입니다. 이 매개 변수는 SERVICE_CONTROL_STATUS_REASON_INFO(1)로 설정해야 합니다.
[in, out] pControlParams
서비스 제어 매개 변수에 대한 포인터입니다. dwInfoLevel이 SERVICE_CONTROL_STATUS_REASON_INFO 경우 이 멤버는 SERVICE_CONTROL_STATUS_REASON_PARAMS 구조체에 대한 포인터입니다.
반환 값
함수가 성공하면 반환 값이 0이 아닙니다.
함수가 실패하면 반환 값은 0입니다. 확장 오류 정보를 가져오려면 GetLastError를 호출합니다.
서비스 제어 관리자가 설정할 수 있는 오류 코드는 다음과 같습니다. 다른 오류 코드는 서비스 제어 관리자가 호출하는 레지스트리 함수에서 설정할 수 있습니다.
| 반환 코드 | 설명 |
|---|---|
|
핸들에 필요한 액세스 권한이 없습니다. |
|
다른 실행 중인 서비스가 종속되어 있기 때문에 서비스를 중지할 수 없습니다. |
|
CreateService 또는 OpenService를 사용하여 지정된 핸들을 가져오지 않았거나 핸들이 더 이상 유효하지 않습니다. |
|
dwControl 매개 변수의 요청된 컨트롤 코드가 정의되지 않았거나 dwControl이 SERVICE_CONTROL_STOP 있지만 SERVICE_CONTROL_STATUS_REASON_PARAMS 구조체의 dwReason 또는 pszComment 멤버가 잘못되었습니다. |
|
요청한 제어 코드가 잘못되었거나 서비스에 사용할 수 없습니다. |
|
서비스 상태가 SERVICE_STOPPED, SERVICE_START_PENDING 또는 SERVICE_STOP_PENDING 때문에 요청된 제어 코드를 서비스로 보낼 수 없습니다. |
|
서비스가 시작되지 않았습니다. |
|
서비스에 대한 프로세스가 시작되었지만 StartServiceCtrlDispatcher를 호출하지 않았거나 StartServiceCtrlDispatcher 라는 스레드가 제어 처리기 함수에서 차단될 수 있습니다. |
|
시스템이 종료되고 있습니다. |
설명
ControlServiceEx 함수는 SCM(서비스 제어 관리자)에 요청된 제어 코드를 서비스에 보내도록 요청합니다. SCM은 서비스에서 코드를 수락하도록 지정하고 컨트롤 코드를 보낼 수 있는 상태인 경우 코드를 보냅니다.
SCM은 서비스 제어 알림을 직렬 방식으로 처리합니다. 즉, 한 서비스가 서비스 제어 알림 처리를 완료할 때까지 기다린 후 다음 알림을 보냅니다. 이 때문에 제어 코드를 처리하는 서비스가 있는 경우 ControlServiceEx 에 대한 호출이 30초 동안 차단됩니다. 시간 제한이 만료되면 사용 중인 서비스가 처리기 함수에서 아직 반환되지 않은 경우 ControlServiceEx 는 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) |
| RUNNING | (a) | (a) |
| CONTINUE_PENDING | (a) | (a) |
| PAUSE_PENDING | (a) | (a) |
| 일시 중지됨 | (a) | (a) |
- (a)
- 서비스에서 이 제어 코드를 수락하면 서비스에 요청을 보냅니다. 그렇지 않으면 ControlServiceEx 는 0을 반환하고 GetLastError 는 ERROR_INVALID_SERVICE_CONTROL 반환합니다.
- (b)
- 서비스는 컨트롤을 보낼 수 있는 상태가 아니므로 ControlServiceEx 는 0을 반환하고 GetLastError 는 ERROR_SERVICE_CANNOT_ACCEPT_CTRL 반환합니다.
- (c)
- 서비스가 활성 상태가 아니므로 ControlServiceEx 는 0을 반환하고 GetLastError 는 ERROR_SERVICE_NOT_ACTIVE 반환합니다.
참고
winsvc.h 헤더는 CONTROLServiceEx를 유니코드 전처리기 상수의 정의에 따라 이 함수의 ANSI 또는 유니코드 버전을 자동으로 선택하는 별칭으로 정의합니다. 인코딩 중립 별칭을 인코딩 중립이 아닌 코드와 혼합하면 컴파일 또는 런타임 오류가 발생하는 불일치가 발생할 수 있습니다. 자세한 내용은 함수 프로토타입에 대한 규칙을 참조하세요.
요구 사항
| 지원되는 최소 클라이언트 | Windows Vista [데스크톱 앱만 해당] |
| 지원되는 최소 서버 | Windows Server 2008 [데스크톱 앱만 해당] |
| 대상 플랫폼 | Windows |
| 헤더 | winsvc.h(Windows.h 포함) |
| 라이브러리 | Advapi32.lib |
| DLL | Advapi32.dll |
추가 정보
피드백
출시 예정: 2024년 내내 콘텐츠에 대한 피드백 메커니즘으로 GitHub 문제를 단계적으로 폐지하고 이를 새로운 피드백 시스템으로 바꿀 예정입니다. 자세한 내용은 다음을 참조하세요. https://aka.ms/ContentUserFeedback
다음에 대한 사용자 의견 제출 및 보기