Функция 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

Этот параметр может быть одним из следующих кодов элементов управления.

Этот параметр также может быть определяемым пользователем кодом элемента управления, как описано в следующей таблице.

[in] dwInfoLevel

Уровень сведений для параметров управления службой. Для этого параметра необходимо задать значение SERVICE_CONTROL_STATUS_REASON_INFO (1).

[in, out] pControlParams

Указатель на параметры элемента управления службой. Если параметр dwInfoLevel является SERVICE_CONTROL_STATUS_REASON_INFO, этот элемент является указателем на структуру SERVICE_CONTROL_STATUS_REASON_PARAMS .

Возвращаемое значение

Если функция выполняется успешно, возвращается ненулевое значение.

Если функция выполняется неудачно, возвращается нулевое значение. Дополнительные сведения об ошибке можно получить, вызвав GetLastError.

Диспетчер управления службами может задать следующие коды ошибок. Другие коды ошибок могут задаваться функциями реестра, которые вызываются диспетчером управления службами.

Комментарии

Функция 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 в каждом из возможных состояний службы.

(a)

Если служба принимает этот код управления, отправьте запрос службе; В противном случае ControlServiceEx возвращает ноль, а GetLastError возвращает ERROR_INVALID_SERVICE_CONTROL.

(б)

Служба не находится в состоянии, в котором в нее может быть отправлен элемент управления, поэтому ControlServiceEx возвращает ноль, а GetLastError возвращает ERROR_SERVICE_CANNOT_ACCEPT_CTRL.

(c)

Служба не активна, поэтому ControlServiceEx возвращает ноль, а GetLastError возвращает ERROR_SERVICE_NOT_ACTIVE.

Требования

См. также раздел

CreateService

OpenService

QueryServiceStatusEx

SERVICE_CONTROL_STATUS_REASON_PARAMS

SERVICE_STATUS

Запросы на управление службами

Функции службы

SetServiceObjectSecurity

SetServiceStatus