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

Статья
08/27/2023

Отправляет управляющий код в службу.

Синтаксис

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