Функция ControlService (winsvc.h)

Отправляет код элемента управления в службу.

Чтобы указать дополнительные сведения при остановке службы, используйте функцию ControlServiceEx .

Синтаксис

BOOL ControlService(
  [in]  SC_HANDLE        hService,
  [in]  DWORD            dwControl,
  [out] LPSERVICE_STATUS lpServiceStatus
);

Параметры

[in] hService

Дескриптор службы. Этот дескриптор возвращается функцией OpenService или CreateService . Права доступа, необходимые для этого дескриптора, зависят от запрошенного кода dwControl.

[in] dwControl

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

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

[out] lpServiceStatus

Указатель на структуру SERVICE_STATUS , которая получает последние сведения о состоянии службы. Возвращаемые сведения отражают последнее состояние, о чем служба сообщила диспетчеру управления службами.

Диспетчер элементов управления службами заполняет структуру, только если GetLastError возвращает один из следующих кодов ошибок: NO_ERROR, ERROR_INVALID_SERVICE_CONTROL, ERROR_SERVICE_CANNOT_ACCEPT_CTRL или ERROR_SERVICE_NOT_ACTIVE. В противном случае структура не заполняется.

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

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

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

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

Комментарии

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

(a)

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

(б)

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

(c)

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

Примеры

Пример см. в разделе Остановка службы.

Требования

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

ControlServiceEx

CreateService

OpenService

QueryServiceStatusEx

SERVICE_STATUS

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

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

SetServiceObjectSecurity

SetServiceStatus