Функция RegisterServiceCtrlHandler

Служба вызывает функцию RegisterServiceCtrlHandler, чтобы зарегистрировать функцию, которая обрабатывает ее запросы на управление службой.

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

Синтаксис

Параметры

lpServiceName

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

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

lpHandlerProc

[in] Указатель на обработчика функции, который был зарегистрирован. Дополнительную информацию смотри в описании функции Handler.

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

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

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

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

Замечания

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

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

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

Дескриптор состояния службы не должен быть закрыт.

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

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

Смотри также

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