Поделиться через


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

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

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

Синтаксис

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

Параметры

[in] hService

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

[in] dwControl

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

Код элемента управления Значение
SERVICE_CONTROL_CONTINUE
0x00000003
Уведомляет приостановленную службу о том, что она должна возобновить работу. Дескриптор hService должен иметь право доступа SERVICE_PAUSE_CONTINUE .
SERVICE_CONTROL_INTERROGATE
0x00000004
Уведомляет службу о том, что она должна сообщить о своем текущем состоянии диспетчеру управления службами. Дескриптор hService должен иметь право доступа SERVICE_INTERROGATE .

Обратите внимание, что этот элемент управления обычно не полезен, так как SCM знает о текущем состоянии службы.

SERVICE_CONTROL_NETBINDADD
0x00000007
Уведомляет сетевую службу о наличии нового компонента для привязки. Дескриптор hService должен иметь право доступа SERVICE_PAUSE_CONTINUE . Однако этот код элемента управления является устаревшим; вместо этого используйте функции Plug and Play.
SERVICE_CONTROL_NETBINDDISABLE
0x0000000a
Уведомляет сетевую службу о том, что одна из ее привязок отключена. Дескриптор hService должен иметь право доступа SERVICE_PAUSE_CONTINUE . Однако этот код элемента управления является устаревшим; вместо этого используйте функции Plug and Play.
SERVICE_CONTROL_NETBINDENABLE
0x00000009
Уведомляет сетевую службу о том, что отключенная привязка включена. Дескриптор hService должен иметь право доступа SERVICE_PAUSE_CONTINUE . Однако этот код элемента управления является устаревшим; вместо этого используйте функции Plug and Play.
SERVICE_CONTROL_NETBINDREMOVE
0x00000008
Уведомляет сетевую службу о том, что компонент для привязки удален. Дескриптор hService должен иметь право доступа SERVICE_PAUSE_CONTINUE . Однако этот код элемента управления является устаревшим; вместо этого используйте функции Plug and Play.
SERVICE_CONTROL_PARAMCHANGE
0x00000006
Уведомляет службу об изменении параметров запуска. Дескриптор hService должен иметь право доступа SERVICE_PAUSE_CONTINUE .
SERVICE_CONTROL_PAUSE
0x00000002
Уведомляет службу о том, что она должна приостановиться. Дескриптор hService должен иметь право доступа SERVICE_PAUSE_CONTINUE .
SERVICE_CONTROL_STOP
0x00000001
Уведомляет службу о том, что она должна остановиться. Дескриптор hService должен иметь право доступа SERVICE_STOP .

После отправки запроса на остановку в службу не следует отправлять другие элементы управления в службу.

 

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

Код элемента управления Значение
Диапазон от 128 до 255
Служба определяет действие, связанное с кодом элемента управления. Дескриптор 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.

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

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

Состояние службы Stop Других элементов управления.
STOPPED (c) (c)
STOP_PENDING (б) (б)
START_PENDING (a) (б)
RUNNING (a) (a)
CONTINUE_PENDING (a) (a)
PAUSE_PENDING (a) (a)
ПРИОСТАНОВЛЕНА (a) (a)
(a)
Если служба принимает этот код управления, отправьте запрос службе; В противном случае ControlService возвращает ноль, а GetLastErrorERROR_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

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

ControlServiceEx

CreateService

OpenService

QueryServiceStatusEx

SERVICE_STATUS

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

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

SetServiceObjectSecurity

SetServiceStatus