Функция SetServiceStatus

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

Синтаксис

Параметры

hServiceStatus

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

lpServiceStatus

[in] Указатель на структуру SERVICE_STATUS, которая содержит в своем составе последнюю информацию о статусе для вызывающей службы.

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

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

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

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

Замечания

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

Когда служба получает запрос на управление,  функция  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>.

Демонстрационный код

Пример смотри в статье Запись функции ServiceMain..

Смотри также

Обзор Службы, Функции, используемые службами,  HandlerEx, RegisterServiceCtrlHandlerEx,  ServiceMain, SetServiceBits, SERVICE_STATUS