Функция RegisterServiceCtrlHandlerEx

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

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

Синтаксис

Параметры

lpServiceName

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

lpHandlerProc

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

lpContext

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

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

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

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

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

Замечания

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

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

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

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

Смотри также

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