Функция 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 .
Возвращаемое значение
Если функция выполняется успешно, возвращается ненулевое значение.
Если функция выполняется неудачно, возвращается нулевое значение. Дополнительные сведения об ошибке можно получить, вызвав GetLastError.
Диспетчер управления службами может задать следующие коды ошибок. Другие коды ошибок могут задаваться функциями реестра, которые вызываются диспетчером управления службами.
| Код возврата | Описание |
|---|---|
|
Дескриптор не имеет необходимых прав доступа. |
|
Невозможно остановить службу, так как от нее зависят другие работающие службы. |
|
Указанный дескриптор не был получен с помощью CreateService или OpenService, либо дескриптор больше недействителен. |
|
Запрошенный код элемента управления в параметре dwControl не определен, или dwControl является SERVICE_CONTROL_STOP но члены dwReason или pszCommentструктуры SERVICE_CONTROL_STATUS_REASON_PARAMS являются недопустимыми. |
|
Запрошенный управляющий код недопустим или неприемлем для данной службы. |
|
Не удается отправить запрошенный управляющий код в службу, так как служба находится в состоянии SERVICE_STOPPED, SERVICE_START_PENDING или SERVICE_STOP_PENDING. |
|
Служба не запущена. |
|
Процесс для службы был запущен, но он не вызвал StartServiceCtrlDispatcher, или поток, который вызвал StartServiceCtrlDispatcher , может быть заблокирован в функции обработчика управления. |
|
Система завершает работу. |
Комментарии
Функция ControlServiceEx запрашивает диспетчер управления службами (SCM) для отправки запрошенного кода элемента управления в службу. SCM отправляет код, если служба указала, что она будет принимать код, и находится в состоянии, в котором может быть отправлен ей управляющий код.
SCM последовательно обрабатывает уведомления об управлении службой. Он ожидает завершения обработки уведомления элемента управления службой, прежде чем отправлять следующее. Из-за этого вызов ControlServiceEx блокируется в течение 30 секунд, если какая-либо служба занята обработкой кода управления. Если занятая служба по-прежнему не возвращается из функции обработчика по истечении времени ожидания, ControlServiceEx завершается сбоем с 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)
- Если служба принимает этот код управления, отправьте запрос службе; В противном случае ControlServiceEx возвращает ноль, а GetLastError возвращает ERROR_INVALID_SERVICE_CONTROL.
- (б)
- Служба не находится в состоянии, в котором в нее может быть отправлен элемент управления, поэтому ControlServiceEx возвращает ноль, а GetLastError возвращает ERROR_SERVICE_CANNOT_ACCEPT_CTRL.
- (c)
- Служба не активна, поэтому ControlServiceEx возвращает ноль, а GetLastError возвращает ERROR_SERVICE_NOT_ACTIVE.
Примечание
Заголовок winsvc.h определяет ControlServiceEx как псевдоним, который автоматически выбирает версию ANSI или Юникод этой функции на основе определения константы препроцессора ЮНИКОД. Сочетание использования псевдонима, не зависящий от кодировки, с кодом, не зависящим от кодировки, может привести к несоответствиям, которые приводят к ошибкам компиляции или среды выполнения. Дополнительные сведения см. в разделе Соглашения для прототипов функций.
Требования
| Минимальная версия клиента | Windows Vista [только классические приложения] |
| Минимальная версия сервера | Windows Server 2008 [только классические приложения] |
| Целевая платформа | Windows |
| Header | winsvc.h (включая Windows.h) |
| Библиотека | Advapi32.lib |
| DLL | Advapi32.dll |
См. также раздел
SERVICE_CONTROL_STATUS_REASON_PARAMS