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

  • Статья

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

Тип LPHANDLER_FUNCTION_EX определяет указатель на эту функцию. HandlerEx — это заполнитель для определяемого приложением имени.

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

Синтаксис

LPHANDLER_FUNCTION_EX LphandlerFunctionEx;

DWORD LphandlerFunctionEx(
  [in] DWORD dwControl,
  [in] DWORD dwEventType,
  [in] LPVOID lpEventData,
  [in] LPVOID lpContext
)
{...}

Параметры

[in] dwControl

Код элемента управления. Этот параметр может принимать одно из указанных ниже значений.

Код элемента управления Значение
SERVICE_CONTROL_CONTINUE
0x00000003
 Уведомляет приостановленную службу о том, что она должна возобновиться.
SERVICE_CONTROL_INTERROGATE
0x00000004
 Уведомляет службу, чтобы сообщить о ее текущем состоянии диспетчеру управления службами.

Обработчик должен просто вернуть NO_ERROR; SCM знает о текущем состоянии службы.
SERVICE_CONTROL_NETBINDADD
0x00000007
 Уведомляет сетевую службу о наличии нового компонента для привязки. Служба должна привязаться к новому компоненту.

Вместо этого приложения должны использовать Plug and Play функциональные возможности.
SERVICE_CONTROL_NETBINDDISABLE
0x0000000a
 Уведомляет сетевую службу о том, что одна из ее привязок отключена. Служба должна перечитать сведения о привязке и удалить привязку.

Вместо этого приложения должны использовать Plug and Play функциональные возможности.
SERVICE_CONTROL_NETBINDENABLE
0x00000009
 Уведомляет сетевую службу о том, что отключенная привязка включена. Служба должна перечитать сведения о привязке и добавить новую привязку.

Вместо этого приложения должны использовать Plug and Play функциональные возможности.
SERVICE_CONTROL_NETBINDREMOVE
0x00000008
 Уведомляет сетевую службу о том, что компонент для привязки был удален. Служба должна перечитать сведения о привязке и отменить привязку удаленного компонента.

Вместо этого приложения должны использовать Plug and Play функциональные возможности.
SERVICE_CONTROL_PARAMCHANGE
0x00000006
 Уведомляет службу о том, что параметры запуска для конкретной службы были изменены. Служба должна перечитать параметры запуска.
SERVICE_CONTROL_PAUSE
0x00000002
 Уведомляет службу о том, что она должна приостановить работу.
SERVICE_CONTROL_PRESHUTDOWN
0x0000000F
 Уведомляет службу о том, что система завершит работу. Службы, которым требуется дополнительное время для выполнения задач очистки за пределами жесткого ограничения времени при завершении работы системы, могут использовать это уведомление. Диспетчер управления службами отправляет это уведомление приложениям, зарегистрированным для него перед отправкой уведомления SERVICE_CONTROL_SHUTDOWN приложениям, зарегистрированным для этого уведомления.

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

Windows Server 2003 и Windows XP: Это значение не поддерживается.
SERVICE_CONTROL_SHUTDOWN
0x00000005
 Уведомляет службу о завершении работы системы, чтобы служба может выполнять задачи очистки. Обратите внимание, что службы, которые регистрируются для получения уведомлений SERVICE_CONTROL_PRESHUTDOWN , не могут получать это уведомление, так как они уже остановлены.

Если служба принимает этот код элемента управления, она должна остановиться после выполнения задач очистки и возврата NO_ERROR. После того как SCM отправит этот код элемента управления, он не будет отправлять другие коды управления в службу.

Дополнительные сведения см. в разделе "Примечания" этого раздела.
SERVICE_CONTROL_STOP
0x00000001
 Уведомляет службу о том, что она должна остановиться.

Если служба принимает этот код управления, она должна остановиться после получения и возврата NO_ERROR. После того как SCM отправит этот код элемента управления, он не будет отправлять другие коды управления в службу. Windows XP: Если служба возвращает NO_ERROR и продолжает выполняться, она продолжает получать коды управления. Это поведение изменилось начиная с Windows Server 2003 и Windows XP с пакетом обновления 2 (SP2).
 

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

Код элемента управления Значение
SERVICE_CONTROL_DEVICEEVENT
0x0000000B
 Уведомляет службу событий устройства. (Служба должна быть зарегистрирована для получения этих уведомлений с помощью функции RegisterDeviceNotification .) Параметры dwEventType и lpEventData содержат дополнительные сведения.
SERVICE_CONTROL_HARDWAREPROFILECHANGE
0x0000000C
 Уведомляет службу о том, что профиль оборудования компьютера изменился. Параметр dwEventType содержит дополнительные сведения.
SERVICE_CONTROL_POWEREVENT
0x0000000D
 Уведомляет службу системных событий питания. Параметр dwEventType содержит дополнительные сведения. Если параметр dwEventType имеет значение PBT_POWERSETTINGCHANGE, параметр lpEventData также содержит дополнительные сведения.
SERVICE_CONTROL_SESSIONCHANGE
0x0000000E
 Уведомляет службу событий изменения сеанса. Обратите внимание, что служба будет получать уведомления о входе пользователя только в том случае, если она полностью загружена перед попыткой входа. Параметры dwEventType и lpEventData содержат дополнительные сведения.
SERVICE_CONTROL_TIMECHANGE
0x00000010
 Уведомляет службу о том, что системное время изменилось. Параметр lpEventData содержит дополнительные сведения. Параметр dwEventType не используется.

Windows Server 2008, Windows Vista, Windows Server 2003 и Windows XP: Этот код элемента управления не поддерживается.
SERVICE_CONTROL_TRIGGEREVENT
0x00000020
 Уведомляет службу, зарегистрированную для события триггера службы , о том, что произошло событие.

Windows Server 2008, Windows Vista, Windows Server 2003 и Windows XP: Этот код элемента управления не поддерживается.
SERVICE_CONTROL_USERMODEREBOOT
0x00000040
 Уведомляет службу о том, что пользователь инициировал перезагрузку.

Windows Server 2008 R2, Windows 7, Windows Server 2008, Windows Vista, Windows Server 2003 и Windows XP: Этот код элемента управления не поддерживается.
 

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

Код элемента управления Значение
Диапазон от 128 до 255.
 Служба определяет действие, связанное с кодом элемента управления.

[in] dwEventType

Тип события, которое произошло. Этот параметр используется, если dwControl имеет значение SERVICE_CONTROL_DEVICEEVENT, SERVICE_CONTROL_HARDWAREPROFILECHANGE, SERVICE_CONTROL_POWEREVENT или SERVICE_CONTROL_SESSIONCHANGE. В противном случае значение равно нулю.

Если dwControlSERVICE_CONTROL_DEVICEEVENT, этот параметр может иметь одно из следующих значений:

Если dwControlSERVICE_CONTROL_HARDWAREPROFILECHANGE, этот параметр может иметь одно из следующих значений: Если dwControlSERVICE_CONTROL_POWEREVENT, этот параметр может быть одним из значений, указанных в параметре wParamсообщения WM_POWERBROADCAST .

Если dwControlSERVICE_CONTROL_SESSIONCHANGE, этот параметр может быть одним из значений, указанных в параметре wParamсообщения WM_WTSSESSION_CHANGE .

[in] lpEventData

Дополнительные сведения об устройстве, если это необходимо. Формат этих данных зависит от значения параметров dwControl и dwEventType .

Если dwControlSERVICE_CONTROL_DEVICEEVENT, эти данные соответствуют параметру lParam , который приложения получают как часть сообщения WM_DEVICECHANGE .

Если значение dwControlSERVICE_CONTROL_POWEREVENT и dwEventType PBT_POWERSETTINGCHANGE, эти данные являются указателем на структуру POWERBROADCAST_SETTING .

Если dwControlSERVICE_CONTROL_SESSIONCHANGE, этот параметр является указателем на структуру WTSSESSION_NOTIFICATION .

Если dwControlSERVICE_CONTROL_TIMECHANGE, эти данные являются указателем на структуру SERVICE_TIMECHANGE_INFO .

[in] lpContext

Определяемые пользователем данные, передаваемые из RegisterServiceCtrlHandlerEx. Если несколько служб совместно используют процесс, параметр lpContext может помочь определить службу.

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

Возвращаемое значение для этой функции зависит от полученного кода элемента управления.

В следующем списке указаны правила для этого возвращаемого значения:

  • Как правило, если служба не обрабатывает элемент управления, верните ERROR_CALL_NOT_IMPLEMENTED. Однако служба должна возвращать NO_ERROR для SERVICE_CONTROL_INTERROGATE даже если служба не обрабатывает ее.
  • Если служба обрабатывает SERVICE_CONTROL_STOP или SERVICE_CONTROL_SHUTDOWN, вернитесь NO_ERROR.
  • Если служба обрабатывает SERVICE_CONTROL_DEVICEEVENT, верните NO_ERROR , чтобы предоставить запрос и код ошибки, чтобы отклонить запрос.
  • Если служба обрабатывает SERVICE_CONTROL_HARDWAREPROFILECHANGE, верните NO_ERROR , чтобы предоставить запрос и код ошибки, чтобы отклонить запрос.
  • Если служба обрабатывает SERVICE_CONTROL_POWEREVENT, верните NO_ERROR , чтобы предоставить запрос и код ошибки, чтобы отклонить запрос.
  • Для всех остальных кодов управления дескрипторов службы верните NO_ERROR.

Комментарии

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

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

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

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

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

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

HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control

Не забудьте обрабатывать события устройства Plug and Play как можно быстрее; в противном случае система может перестать отвечать. Если обработчик событий выполняет операцию, которая может блокировать выполнение (например, ввод-вывод), лучше всего запустить другой поток, чтобы выполнить операцию асинхронно.

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

Требования

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

См. также раздел

POWERBROADCAST_SETTING

RegisterDeviceNotification

RegisterServiceCtrlHandlerEx

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

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

ServiceMain

SetServiceStatus

WM_DEVICECHANGE

WM_POWERBROADCAST

WM_WTSSESSION_CHANGE

WTSSESSION_NOTIFICATION