Поделиться через

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

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

Синтаксис

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
 Запись службы была указана неправильно при вызове функции StartServiceCtrlDispat cher.

Замечания

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

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

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

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

Заметка

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

Требования

Требование Ценность
минимальные поддерживаемые клиентские Windows XP [только классические приложения]
минимальный поддерживаемый сервер Windows Server 2003 [только классические приложения]
целевая платформа Виндоус
заголовка winsvc.h (включая Windows.h)
библиотеки Advapi32.lib
DLL Advapi32.dll

См. также

CreateService

HandlerEx

функции обработчика управления службами

Функции службы

ServiceMain

SetServiceStatus

  • Last updated on