Функция ControlService отправляет управляющий код службе.
Синтаксис
BOOL ControlService( SC_HANDLE hService, DWORD dwControl, LPSERVICE_STATUS lpServiceStatus ); |
| Управляющий код | Предназначение |
|---|---|
| SERVICE_CONTROL_CONTINUE | Уведомляет, что временно остановленный сервис должен возобновить работу. Дескриптор hService должен иметь право доступа SERVICE_PAUSE_CONTINUE. |
| SERVICE_CONTROL_INTERROGATE | Уведомляет сервис, что он должен сообщить информацию о его текущем состоянии Диспетчеру управления сервисами (SCM). Дескриптор hService должен иметь право доступа SERVICE_INTERROGATE. |
| SERVICE_CONTROL_NETBINDADD | Уведомляет сетевой
сервис, что есть новый компонент для
соединения. Дескриптор hService должен
иметь право доступа SERVICE_PAUSE_CONTINUE. Однако, этот
управляющий код не рекомендуется
применять; вместо него
используйте функциональные
возможности технологии Plug and Play.
Windows NT: Это значение не поддерживается. |
| SERVICE_CONTROL_NETBINDDISABLE | Уведомляет сетевой
сервис, что одна из его связей
заблокирована. Дескриптор hService
должен иметь право доступа
SERVICE_PAUSE_CONTINUE. Однако, этот управляющий код не
рекомендуется применять; вместо
него используйте функциональные
возможности технологии Plug and Play.
Windows NT: Это значение значение не поддерживается. |
| SERVICE_CONTROL_NETBINDENABLE | Уведомляет сетевой
сервис, что одна из его
заблокированных связей включена.
Дескриптор hService должен иметь право
доступа SERVICE_PAUSE_CONTINUE.
Однако, этот управляющий код не
рекомендуется применять; вместо
него используйте функциональные
возможности технологии Plug and Play.
Windows NT: Это значение значение не поддерживается. |
| SERVICE_CONTROL_NETBINDREMOVE | Уведомляет сетевую
службу о том, что компонент для
связывания был удален. Дескриптор
hService должен иметь право доступа
SERVICE_PAUSE_CONTINUE. Однако, этот
управляющий код не рекомендуется
применять; используйте вместо него
функциональные возможности
технологии Plug and Play
Windows NT: Это значение значение не поддерживается. |
| SERVICE_CONTROL_PARAMCHANGE | Уведомляет службу,
что ее параметры запуска изменились.
Дескриптор hService должен иметь право
доступа SERVICE_PAUSE_CONTINUE.
Windows NT: Это значение не поддерживается. |
| SERVICE_CONTROL_PAUSE | Уведомляет службу, что она должна сделать паузу. Дескриптор hService должен иметь право доступа SERVICE_PAUSE_CONTINUE. |
| SERVICE_CONTROL_STOP | Уведомляет службу, что она должна остановиться. Дескриптор hService должен иметь право доступа SERVICE_STOP. |
Это значение может также быть
управляющим кодом определяемым
пользователем, как описано в следующей
таблице.
| Управляющий код | Предназначение |
|---|---|
| Диапазон от 128 до 255. | Служба определяет действие, связанное с управляющим кодом. Дескриптор hService должен иметь право доступа SERVICE_USER_DEFINED_CONTROL. |
Диспетчер управления службами заполняет поля в структуре только тогда, когда функция ControlService возвращает один из следующих кодов ошибки: NO_ERROR, ERROR_INVALID_SERVICE_CONTROL, ERROR_SERVICE_CANNOT_ACCEPT_CTRL или ERROR_SERVICE_NOT_ACTIVE. Иначе, структура не заполняется.
Если функция завершается успешно, возвращаемое значение является ненулевым.
Если функция завершается ошибкой, возвращаемое значение - нуль. Чтобы получить дополнительную информацию об ошибке, вызовите 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 секунд, если какая-нибудь служба будет занята, обрабатывая управляющий код. Если занятая служба, когда перерыв истекает, все еще не возвратилась из своего обработчика функции, ControlService завершается ошибкой ERROR_SERVICE_REQUEST_TIMEOUT.
Чтобы остановить или запустить службу, требуется дескриптор безопасности, который позволяет Вам сделать это. Дескриптор безопасности по умолчанию предоставляет учетную запись LocalSystem и для членов группы Администраторов и Опытных пользователей останавливать и запускать службы. Чтобы изменять дескриптор безопасности службы, см. статью Модификация DACL для службы.
Функция QueryServiceStatusEx возвращает структуру SERVICE_STATUS_PROCESS, члены dwCurrentState и dwControlsAccepted которой указывают текущее состояние и управления, принятые запущенной службой. Все запущенные службы принимают управляющий код SERVICE_CONTROL_INTERROGATE по умолчанию. Драйверы не принимают управляющих кодов кроме SERVICE_CONTROL_STOP и SERVICE_CONTROL_INTERROGATE. Каждая служба задает другие управляющие коды, которые она принимает, когда вызывает функцию SetServiceStatus, чтобы сообщить о своем состоянии. Служба должна всегда принимать эти коды, когда она запускается, независимо от того что она делает.
Следующая таблица показывает действие Диспетчера управления службами (SCM) в каждом из возможных состояний службы.
| Состояние службы | Останов | Другие управляющие действия |
|---|---|---|
| STOPPED | (c) | (c) |
| STOP_PENDING | (b) | (b) |
| START_PENDING | (a) | (b) |
| RUNNING | (a) | (a) |
| CONTINUE_PENDING | (a) | (a) |
| PAUSE_PENDING | (a) | (a) |
| PAUSED | (a) | (a) |
| Где, | (a) | Если служба принимает этот управляющий код, отправляется запрос службе; иначе, функция ControlService возвращает значение - ноль, а GetLastError возвращает ERROR_INVALID_SERVICE_CONTROL. |
| (b) | Служба не находится в состоянии, в котором ей можно передать управление, так что ControlService возвращает значение - ноль, а GetLastError возвращает ERROR_SERVICE_CANNOT_ACCEPT_CTRL. | |
| (c) | Служба не активна, таким образом ControlService возвращает значение - ноль, а GetLastError возвращает ERROR_SERVICE_NOT_ACTIVE. |
Пример смотри в статье Передача запросов на управление службе.
Смотри также
Обзор Службы, Функции, используемые службами, CreateService, OpenService, QueryServiceStatusEx, SetServiceObjectSecurity, SetServiceStatus, SERVICE_STATUS
|
Размещение и совместимость ControlService |
||
| К |
Windows XP |
Да |
| л |
Windows 2000 Professional |
Да |
| и |
Windows NT Workstation |
Да |
| е |
Windows Me |
Нет |
| н |
Windows 98 |
Нет |
| т |
Windows 95 |
Нет |
| С |
Windows Server 2003 |
Да |
| е | Windows 2000 Server | Да |
| р | Windows NT Server | Да |
| в | ||
| е | ||
| р | ||
|
Используемая библиотека |
Advapi32.lib |
|
| Используемая DLL | advapi32.dll | |
| Заголовочный файл | ||
|
- объявлено в |
Winsvc.h |
|
| - включено в |
Windows.h |
|
| Unicode |
Нет |
|
| Замечания по платформе |
Не имеется |
|