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

Статья
11/20/2024

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

Синтаксис

BOOL ControlServiceExA(
  [in]      SC_HANDLE hService,
  [in]      DWORD     dwControl,
  [in]      DWORD     dwInfoLevel,
  [in, out] PVOID     pControlParams
);

Параметры

[in] hService

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

[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 должен иметь право доступа к 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 , а также членам групп администраторов и пользователей Power Users для остановки и запуска служб. Чтобы изменить дескриптор безопасности службы, см. изменение DACL для службы.

Функция QueryServiceStatusEx возвращает структуру SERVICE_STATUS_PROCESS, dwCurrentState и dwControlsAccepted элементы указывают текущее состояние и элементы управления, принятые запущенной службой. Все запущенные службы принимают код элемента управления SERVICE_CONTROL_INTERROGATE по умолчанию. Драйверы не принимают коды управления, отличные от SERVICE_CONTROL_STOP и SERVICE_CONTROL_INTERROGATE. Каждая служба задает другие коды управления, которые он принимает при вызове функции SetServiceStatus, чтобы сообщить о своем состоянии. Служба всегда должна принимать эти коды при выполнении, независимо от того, что она делает.

В следующей таблице показано действие SCM в каждом из возможных состояний службы.

Состояние службы	Остановка	Другие элементы управления
ОСТАНОВЛЕННЫЙ	(c)	(c)
STOP_PENDING	(b)	(b)
START_PENDING	(a)	(b)
БЕГ	(a)	(a)
CONTINUE_PENDING	(a)	(a)
PAUSE_PENDING	(a)	(a)
ПРИОСТАНОВЛЕНА	(a)	(a)

(a): Если служба принимает этот код управления, отправьте запрос в службу; в противном случае ControlServiceEx возвращает ноль и GetLastError возвращает ERROR_INVALID_SERVICE_CONTROL.
(b): Служба не находится в состоянии, в котором элемент управления может быть отправлен в него, поэтому ControlServiceEx возвращает ноль и GetLastError возвращает ERROR_SERVICE_CANNOT_ACCEPT_CTRL.
(c): Служба не активна, поэтому ControlServiceEx возвращает ноль и возвращает GetLastError возвращает ERROR_SERVICE_NOT_ACTIVE.

Заметка

Заголовок winsvc.h определяет ControlServiceEx как псевдоним, который автоматически выбирает версию ANSI или Юникод этой функции на основе определения константы препроцессора ЮНИКОДа. Сочетание использования псевдонима, нейтрального для кодирования, с кодом, не зависящим от кодирования, может привести к несоответствиям, которые приводят к ошибкам компиляции или среды выполнения. Дополнительные сведения см. в соглашениях о прототипах функций.

Требования

Требование	Ценность
минимальные поддерживаемые клиентские	Windows Vista [только классические приложения]
минимальный поддерживаемый сервер	Windows Server 2008 [только классические приложения]
целевая платформа	Виндоус
заголовка	winsvc.h (включая Windows.h)
библиотеки	Advapi32.lib
DLL	Advapi32.dll