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

Статья
08/27/2023

Обновления сведения о состоянии диспетчера управления службами для вызывающей службы.

Синтаксис

BOOL SetServiceStatus(
  [in] SERVICE_STATUS_HANDLE hServiceStatus,
  [in] LPSERVICE_STATUS      lpServiceStatus
);

Параметры

[in] hServiceStatus

Дескриптор структуры сведений о состоянии для текущей службы. Этот дескриптор возвращается функцией RegisterServiceCtrlHandlerEx .

[in] lpServiceStatus

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

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

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

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

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

Код возврата	Описание
ERROR_INVALID_DATA	Указанная структура состояния службы недопустима.
ERROR_INVALID_HANDLE	Указанный дескриптор недопустим.

Функция ServiceMain сначала вызывает функцию RegisterServiceCtrlHandlerEx , чтобы получить SERVICE_STATUS_HANDLE службы. Затем он немедленно вызывает функцию SetServiceStatus , чтобы уведомить диспетчер управления службами о том, что его состояние SERVICE_START_PENDING. Во время инициализации служба может предоставить обновленное состояние, чтобы указать, что она выполняется, но ей требуется больше времени. Распространенная ошибка заключается в том, что служба выполняет инициализацию потока main, а отдельный поток продолжает вызывать SetServiceStatus, чтобы диспетчер управления службами не помечал его как завис. Однако если поток main зависает, запуск службы завершается бесконечным циклом, так как рабочий поток продолжает сообщать о том, что поток main выполняется.

После обработки запроса элемента управления функция Handler службы должна вызвать SetServiceStatus , если состояние службы изменится, чтобы сообщить о новом состоянии диспетчеру управления службами. Это необходимо сделать только при изменении состояния службы, например при обработке элементов управления остановкой или завершением работы. Служба также может использовать эту функцию в любое время из любого потока службы, чтобы уведомить диспетчер управления службой об изменениях состояния, например, когда служба должна остановиться из-за ошибки, допускаемой для восстановления.

Служба может вызывать эту функцию только после вызова Метода RegisterServiceCtrlHandlerEx для получения дескриптора состояния службы.

Если служба вызывает SetServiceStatus с элементом dwCurrentState, равным SERVICE_STOPPED, а для элемента dwWin32ExitCode задано ненулевое значение, в журнал системных событий записывается следующая запись:

   Event ID    = 7023
   Source      = Service Control Manager
   Type        = Error
   Description = <ServiceName> terminated with the following error:
                 <ExitCode>.

Ниже приведены рекомендации по вызову этой функции.

Инициализируйте все поля в структуре SERVICE_STATUS, гарантируя наличие допустимых значений проверка точек и указаний ожидания для ожидающих состояний. Используйте разумные указания на ожидание.
Не регистрируйтесь для принятия элементов управления, пока состояние SERVICE_START_PENDING или служба может аварийно завершить работу. После завершения инициализации примите код SERVICE_CONTROL_STOP.
Вызывайте эту функцию со значениями контрольных точек и подсказок ожидания, только если служба выполняет задачи, связанные с ожидающей операцией запуска, остановки, приостановки или продолжения. В противном случае SCM не сможет определить, зависла ли служба.
Введите остановленное состояние с соответствующим кодом выхода в случае сбоя ServiceMain .
Если состояние SERVICE_STOPPED, выполните всю необходимую очистку и вызовите SetServiceStatus только один раз. Эта функция выполняет вызов LRPC к SCM. Первый вызов функции в состоянии SERVICE_STOPPED закрывает дескриптор контекста RPC, и все последующие вызовы могут привести к сбою процесса.
Не пытайтесь выполнить дополнительные действия после вызова SetServiceStatus с SERVICE_STOPPED, так как процесс обслуживания может быть завершен в любое время.

Примеры

Пример см. в разделе Написание функции ServiceMain.

Требования

Требование	Значение
Минимальная версия клиента	Windows XP [только классические приложения]
Минимальная версия сервера	Windows Server 2003 [только классические приложения]
Целевая платформа	Windows
Header	winsvc.h (включая Windows.h)
Библиотека	Advapi32.lib
DLL	Advapi32.dll