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

  • Статья

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

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

Эта функция заменяет функцию обработчика элемента управления Handler , используемую с функцией 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).
 

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

Код элемента управления Значение
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. В противном случае значение равно нулю.

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

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

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

[in] lpEventData

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

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

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

Если dwControl имеет SERVICE_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 .

Диспетчер элементов управления в потоке main службы вызывает функцию обработчика элементов управления для указанной службы всякий раз, когда получает запрос на управление от диспетчера управления службой. После обработки запроса элемента управления обработчик элементов управления должен вызвать 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