Функция HandlerEx

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

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

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

Синтаксис

DWORD WINAPI HandlerEx(
  DWORD dwControl,
  DWORD dwEventType,
  LPVOID lpEventData,
  LPVOID lpContext
);
 
Параметры
dwControl
[in] Управляющий код. Этот параметр может быть одним из следующих значений.

 

Управляющий код Предназначение
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. Служба определяет действие, связанное с управляющим кодом.
dwEventType
[in] Тип события, которое произошло. Этот параметр используется, если dwControl - SERVICE_CONTROL_DEVICEEVENT, SERVICE_CONTROL_HARDWAREPROFILECHANGE, SERVICE_CONTROL_POWEREVENT или SERVICE_CONTROL_SESSIONCHANGE. Иначе, этот параметр - ноль.

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

 

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

Если dwControl - SERVICE_CONTROL_POWEREVENT, этот параметр может быть одним из значений, заданных в параметре wParam сообщения WM_POWERBROADCAST.

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

lpEventData
[in] Дополнительная информация об устройстве, если требуется. Формат этих данных зависит от значения параметров dwControl и dwEventType. Если dwEventType - SERVICE_CONTROL_DEVICEEVENT, эти данные соответствуют параметру lParam, который приложения получают как часть сообщения WM_DEVICECHANGE. Если dwEventType - SERVICE_CONTROL_POWEREVENT, эти данные соответствуют параметру lParam, который приложения получают как часть сообщения WM_POWERBROADCAST. Если dwEventType - SERVICE_CONTROL_SESSIONCHANGE, этот параметр - структура WTSSESSION_NOTIFICATION.

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

Нет
 Замечания по платформе

Не имеется

 

Назад в оглавление
На главную страницу
На оглавление справки

Hosted by uCoz