Функция RegisterServiceCtrlHandlerEx

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

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

Синтаксис

SERVICE_STATUS_HANDLE RegisterServiceCtrlHandlerEx(
  LPCTSTR lpServiceName,
  LPHANDLER_FUNCTION_EX lpHandlerProc,
  LPVOID lpContext
);

Параметры

lpServiceName

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

lpHandlerProc

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

lpContext

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

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

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

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

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

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

Замечания

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

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

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

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

Смотри также

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

Размещение и совместимость RegisterServiceCtrlHandlerEx 

К Windows XP Да 
л Windows 2000 Professional Да
и Windows NT Нет
е Windows Me Нет
н Windows 98 Нет
т Windows 95 Нет
 
С Windows Server 2003 Да
е Windows 2000 Server Да
р Windows NT Server Нет
в    
е    
р    
Используемая библиотека Advapi32.lib
Используемая DLL advapi32.dll
 Заголовочный файл  
- объявлено в Winsvc.h
 - включено в Windows.h
 Unicode Реализуется как RegisterServiceCtrlHandlerExW (Unicode) и RegisterServiceCtrlHandlerExA (ANSI)
 Замечания по платформе Не имеется

 

Назад в оглавление
На главную страницу
В оглавление справки

Hosted by uCoz