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

Статья
03/09/2024

Регистрирует функцию для обработки запросов управления службой.

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

Синтаксис

SERVICE_STATUS_HANDLE RegisterServiceCtrlHandlerA(
  [in] LPCSTR             lpServiceName,
  [in] LPHANDLER_FUNCTION lpHandlerProc
);

Параметры

[in] lpServiceName

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

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

[in] lpHandlerProc

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

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

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

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

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

Код возврата	Описание
ERROR_NOT_ENOUGH_MEMORY	Недостаточно памяти для преобразования строкового параметра ANSI в Юникод. Эта ошибка не возникает для параметров строки Юникода.
ERROR_SERVICE_NOT_IN_EXE	Запись службы была указана неправильно, когда процесс вызывал функцию StartServiceCtrlDispatcher .

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

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

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

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

Примеры

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

Примечание

Заголовок winsvc.h определяет RegisterServiceCtrlHandler как псевдоним, который автоматически выбирает версию ANSI или Юникод этой функции на основе определения константы препроцессора UNICODE. Сочетание использования псевдонима, не зависящий от кодировки, с кодом, не зависящим от кодировки, может привести к несоответствиям, которые приводят к ошибкам компиляции или среды выполнения. Дополнительные сведения см. в разделе Соглашения для прототипов функций.

Требования

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