Функция HandlerEx - определенная приложением функция обратного вызова, используемая с функцией RegisterServiceCtrlHandlerEx. Сервисная программа может использовать ее как функцию обрабатывающей программы управления специфической службы.
Тип LPHANDLER_FUNCTION_EX определяет указатель на эту функцию. HandlerEx - имя - заместитель для определяемого программой имени.
Эта функция заменяет функцию обрабатывающей программы управления Handler, используемую с функцией RegisterServiceCtrlHandler. Служба может использовать любую обрабатывающую программу управления, но новая обрабатывающая программа управления поддерживает определенные пользователем контекстные данные и дополнительные расширенные управляющие коды.
Синтаксис
DWORD WINAPI HandlerEx( DWORD dwControl, DWORD dwEventType, LPVOID lpEventData, LPVOID lpContext ); |
Параметры
Управляющий код | Предназначение |
---|---|
SERVICE_CONTROL_CONTINUE | Уведомляет, что временно остановленная служба должна возобновить работу. |
SERVICE_CONTROL_INTERROGATE | Уведомляет службу, что она должна сообщить информацию о своем текущем состоянии диспетчеру управления службами (SCM). |
SERVICE_CONTROL_NETBINDADD | Уведомляет сетевую
службу, что есть новый компонент для
соединения. Служба должна соединиться
с новым компонентом.
Приложение вместо него должно использовать функциональные возможности технологии Plug and Play. |
SERVICE_CONTROL_NETBINDDISABLE | Уведомляет сетевую
службу, что одна из его связей
заблокирована. Служба должна
перечитать свою информацию о
связывании и удалить эту связь.
Приложение вместо него должно использовать функциональные возможности технологии Plug and Play. |
SERVICE_CONTROL_NETBINDENABLE | Уведомляет сетевую
службу, что отключенное
связывание включилось в работу.
Служба должен перечитать свою
информацию о связывании и добавить
новое связывание.
Вместо него приложение должно использовать функциональные возможности технологии Plug and Play. |
SERVICE_CONTROL_NETBINDREMOVE | Уведомляет сетевую
службу, что компонент для связывания
был удален. Служба должна перечитать
свою информацию связывания и удалить
связывание с удаленным компонентом.
Вместо этого приложения должны использовать функциональные возможности технологии Plug and Play. |
SERVICE_CONTROL_PARAMCHANGE | Уведомляет службу, что специальные для службы параметры запуска изменились. Служба должна перечитать свои параметры запуска. |
SERVICE_CONTROL_PAUSE | Уведомляет службу, что она должно сделать паузу. |
SERVICE_CONTROL_SHUTDOWN | Уведомляет службу о
том, что система закрывается таким
образом, что служба может выполнить
задачи очистки.
Дополнительную информацию смотри в разделе Замечаний этой статьи. |
SERVICE_CONTROL_STOP | Уведомляет службу о
том, что она должна остановиться. Если служба принимает этот управляющий код, она должна остановиться после его получения. После того, как этот управляющий код отправится, служба не получает управляющие коды. Windows XP/2000: Если служба возвращает значение NO_ERROR и продолжает запускаться, она продолжает получать управляющие коды. Это поведение изменено при запуске под Windows Server 2003 и Windows XP SP2. |
Этот параметр может также быть одним из следующих расширенных управляющих кодов.
Обратите внимание! на то, что эти управляющие коды не поддерживаются функции Handler. |
Управляющий код | Предназначение |
---|---|
SERVICE_CONTROL_DEVICEEVENT | Уведомляет службу событий устройства. (Служба, должна быть зарегистрирована, используя функцию RegisterDeviceNotification, чтобы получить эти уведомления). |
SERVICE_CONTROL_HARDWAREPROFILECHANGE | Уведомляет службу, что профиль аппаратных средств компьютера изменился. |
SERVICE_CONTROL_POWEREVENT | Уведомляет системную службу о событиях электропитания. |
SERVICE_CONTROL_SESSIONCHANGE | Уведомляет службу о
событиях изменения сессии.
Windows 2000: Это значение не поддерживается. |
Этот параметр может также быть определяемым пользователем управляющим кодом, как описано в таблице ниже.
Управляющий код | Предназначение |
---|---|
Диапазон от 128 до 255. | Служба определяет действие, связанное с управляющим кодом. |
Если dwControl - SERVICE_CONTROL_DEVICEEVENT, этот параметр может быть одним из следующих значений:
Если dwControl - SERVICE_CONTROL_HARDWAREPROFILECHANGE, этот параметр может быть одним из следующих значений:
Если dwControl - SERVICE_CONTROL_POWEREVENT, этот параметр может быть одним из значений, заданных в параметре wParam сообщения WM_POWERBROADCAST.
Если dwControl - SERVICE_CONTROL_SESSIONCHANGE, этот параметр может быть одним из значений, заданных в параметре wParam сообщения WM_WTSSESSION_CHANGE.
lpContext
[in] Определяемые пользователем данные передаются от RegisterServiceCtrlHandlerEx. Когда несколько служб совместно используют процесс, lpContext параметр может помочь идентифицировать службу.Возвращаемое значение для этой функции зависит от полученного управляющего кода. Следующий список определяет правила для этого возвращаемого значения:
Когда служба стартует, ее функция ServiceMain должна немедленно вызвать функцию RegisterServiceCtrlHandlerEx, чтобы определить функцию HandlerEx , которая обрабатывает запросы на управление. Чтобы определить управляющие коды, которые будут приняты, используйте функции SetServiceStatus и RegisterDeviceNotification.
Диспетчер управления в пределах главного потока процесса службы вызывает (процедуру) функцию обработки управления для указанной службы всякий раз, когда он получает запрос на управление от диспетчера управления службами. После обработки запроса на управление, обрабатывающая программа управления должна вызвать функцию SetServiceStatus, чтобы сообщить о ее текущем состоянии диспетчеру управления службами.
Когда диспетчер управления службами отправляет управляющий код службе, он ждет обработчика функции, чтобы возвратить значение перед отправкой дополнительных управляющих кодов другим службам. Если обработчик функции не возвращает значение быстро, диспетчер может заблокировать другие службы, чтобы они не получили управляющих кодов.
Управляющий код SERVICE_CONTROL_SHUTDOWN должен обрабатываться только службами, которые должны безусловно очиститься в ходе закрытия, потому имеется только ограниченное время (около 20 секунд) доступное для закрытия службы. После того, как это время истекает, система возобновляет процесс закрытия независимо от того, завершается ли закрытие службы полностью.
Обратите внимание! на то, что если систему оставляют в состоянии закрытия (не перезапускают или не выключают питание), служба, продолжает запускаться. |
Если служба нуждается в большем количестве времени, чтобы очистить память, она должна отправить сообщения о состоянии STOP_PENDING, наряду с указанием ожидать, таким образом диспетчер службы знает, как долго ждать перед оповещением в системе, что закрытие службы завершается полностью. Однако, чтобы воспрепятствовать службе остановить закрытие, есть предел тому, как долго диспетчер службы должен ждать. Чтобы изменять этот срок, модифицируйте значение WaitToKillServiceTimeout в следующем ключе реестра:
HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control |
Убедитесь, что обработка событий устройства "Plug and Play" происходит насколько можно быстрее; иначе, система может стать невосприимчивой. Если ваш обработчик событий должен выполнить операцию, которая может блокировать выполнение ( типа ввода / вывода), лучше запустить другой поток, чтобы выполнить операцию асинхронно.
Смотри также
Обзор Службы, Функции, используемые службами, Handler, RegisterDeviceNotification, RegisterServiceCtrlHandlerEx, ServiceMain, SetServiceStatus, WM_DEVICECHANGE, WM_POWERBROADCAST, WM_WTSSESSION_CHANGE, WTSSESSION_NOTIFICATION
Размещение и совместимость HandlerEx |
||
К |
Windows XP |
Да |
л |
Windows 2000 Professional |
Да |
и |
Windows NT |
Нет |
е |
Windows Me |
Нет |
н |
Windows 98 |
Нет |
т |
Windows 95 |
Нет |
С |
Windows Server 2003 |
Да |
е | Windows 2000 Server | Да |
р | Windows NT Server | Нет |
в | ||
е | ||
р | ||
Используемая библиотека |
- |
|
Используемая DLL | - | |
Заголовочный файл | ||
- объявлено в |
Winsvc.h |
|
- включено в |
Windows.h |
|
Unicode |
Нет |
|
Замечания по платформе |
Не имеется |