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

Статья
08/27/2023

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

Синтаксис

SERVICE_STATUS_HANDLE RegisterServiceCtrlHandlerExA(
  [in]           LPCSTR                lpServiceName,
  [in]           LPHANDLER_FUNCTION_EX lpHandlerProc,
  [in, optional] LPVOID                lpContext
);

Параметры

[in] lpServiceName

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

[in] lpHandlerProc

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

[in, optional] lpContext

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

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

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

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

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

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

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

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

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

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

Примечание

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

Требования

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