функция обратного вызова LPHANDLER_FUNCTION (winsvc.h)

Статья
08/27/2023

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

Тип LPHANDLER_FUNCTION определяет указатель на эту функцию. Обработчик — это заполнитель для имени, определяемого приложением.

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

Синтаксис

LPHANDLER_FUNCTION LphandlerFunction;

void LphandlerFunction(
  DWORD dwControl
)
{...}

Параметры

dwControl

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

None

Remarks

При запуске службы ее функция ServiceMain должна немедленно вызвать функцию RegisterServiceCtrlHandler , чтобы указать функцию Handler для обработки запросов управления.

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

Функция обработчика элемента управления предназначена для получения уведомления и немедленного возврата. Функция обратного вызова должна сохранить свои параметры и создать другие потоки для выполнения дополнительной работы. (Перед остановкой службы приложение должно убедиться, что такие потоки завершились.) В частности, обработчику элементов управления следует избегать операций, которые могут блокироваться, таких как блокировка, так как это может привести к взаимоблокировке или перестать отвечать системе.

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

Код управления SERVICE_CONTROL_SHUTDOWN должен обрабатываться только службами, которые должны полностью очиститься во время завершения работы, так как для завершения работы службы доступно ограниченное время (около 20 секунд). По истечении этого времени завершение работы системы продолжается независимо от того, завершено ли завершение работы службы. Обратите внимание, что если система остается в состоянии завершения работы (не перезапущена или выключена), служба продолжает работать. Если служба регистрируется для принятия SERVICE_CONTROL_SHUTDOWN, она должна обрабатывать код управления и своевременно останавливаться. В противном случае служба может увеличить время, необходимое для завершения работы системы, так как система должна дождаться полного периода времени, необходимого для завершения работы службы, прежде чем продолжить работу системы.

Если службе требуется больше времени для очистки, она должна отправлять STOP_PENDING сообщения о состоянии вместе с указанием ожидания, чтобы контроллер службы знал, сколько времени следует ждать, прежде чем сообщить системе о завершении работы службы. Тем не менее, чтобы предотвратить остановку работы службы, существует ограничение на время ожидания контроллера службы. Если служба завершает работу с помощью оснастки "Службы", ограничение составляет 125 секунд. Если операционная система перезагружается, ограничение времени указывается в значении WaitToKillServiceTimeout следующего раздела реестра:

HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control

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

Примеры

Пример см. в разделе Написание функции обработчика элемента управления.

Требования

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