Функция 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. В противном случае структура не заполняется.
Возвращаемое значение
Если функция выполняется успешно, возвращается ненулевое значение.
Если функция выполняется неудачно, возвращается нулевое значение. Дополнительные сведения об ошибке можно получить, вызвав 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 и членам групп "Администраторы" и "Опытные пользователи" останавливать и запускать службы. Чтобы изменить дескриптор безопасности службы, см. раздел Изменение daCL для службы.
Функция QueryServiceStatusEx возвращает структуру SERVICE_STATUS_PROCESS , элементы dwCurrentState и dwControlsAccepted указывают на текущее состояние и элементы управления, принятые запущенной службой. Все запущенные службы по умолчанию принимают код элемента управления SERVICE_CONTROL_INTERROGATE . Драйверы не принимают коды управления, кроме SERVICE_CONTROL_STOP и SERVICE_CONTROL_INTERROGATE. Каждая служба указывает другие коды элементов управления, которые она принимает при вызове функции SetServiceStatus , чтобы сообщить о своем состоянии. Служба всегда должна принимать эти коды при выполнении, независимо от того, что она делает.
В следующей таблице показано действие SCM в каждом из возможных состояний службы.
| Состояние службы | Stop | Других элементов управления. |
|---|---|---|
| STOPPED | (c) | (c) |
| STOP_PENDING | (б) | (б) |
| START_PENDING | (a) | (б) |
| RUNNING | (a) | (a) |
| CONTINUE_PENDING | (a) | (a) |
| PAUSE_PENDING | (a) | (a) |
| ПРИОСТАНОВЛЕНА | (a) | (a) |
- (a)
- Если служба принимает этот код управления, отправьте запрос службе; В противном случае ControlService возвращает ноль, а GetLastError — ERROR_INVALID_SERVICE_CONTROL.
- (б)
- Служба не находится в состоянии, в котором в нее может быть отправлен элемент управления, поэтому ControlService возвращает ноль, а GetLastError возвращает ERROR_SERVICE_CANNOT_ACCEPT_CTRL.
- (c)
- Служба не активна, поэтому ControlService возвращает ноль, а GetLastError возвращает ERROR_SERVICE_NOT_ACTIVE.
Примеры
Пример см. в разделе Остановка службы.
Требования
| Требование | Значение |
|---|---|
| Минимальная версия клиента | Windows XP [только классические приложения] |
| Минимальная версия сервера | Windows Server 2003 [только классические приложения] |
| Целевая платформа | Windows |
| Header | winsvc.h (включая Windows.h) |
| Библиотека | AdvApi32.lib |
| DLL | AdvApi32.dll |