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


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

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

Управляющий код Значение
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.

[in] dwInfoLevel

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

[in, out] pControlParams

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

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

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

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

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

Код возврата Описание
ERROR_ACCESS_DENIED
Дескриптор не имеет необходимых прав доступа.
ERROR_DEPENDENT_SERVICES_RUNNING
Невозможно остановить службу, так как от нее зависят другие работающие службы.
ERROR_INVALID_HANDLE
Указанный дескриптор не был получен с помощью CreateService или OpenService, либо дескриптор больше недействителен.
ERROR_INVALID_PARAMETER
Запрошенный код элемента управления в параметре dwControl не определен, или dwControl является SERVICE_CONTROL_STOP но члены dwReason или pszCommentструктуры SERVICE_CONTROL_STATUS_REASON_PARAMS являются недопустимыми.
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
Система завершает работу.

Комментарии

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

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

CreateService

OpenService

QueryServiceStatusEx

SERVICE_CONTROL_STATUS_REASON_PARAMS

SERVICE_STATUS

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

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

SetServiceObjectSecurity

SetServiceStatus