Функция NotifyServiceStatusChangeA (winsvc.h)

Позволяет приложению получать уведомления при создании или удалении указанной службы или при изменении ее состояния.

Синтаксис

DWORD NotifyServiceStatusChangeA(
  [in] SC_HANDLE        hService,
  [in] DWORD            dwNotifyMask,
  [in] PSERVICE_NOTIFYA pNotifyBuffer
);

Параметры

[in] hService

Дескриптор для службы или диспетчера управления службой. Дескрипторы служб возвращаются функцией OpenService или CreateService и должны иметь право доступа SERVICE_QUERY_STATUS. Дескрипторы диспетчера управления службами возвращаются функцией OpenSCManager и должны иметь право доступа к SC_MANAGER_ENUMERATE_SERVICE. Дополнительные сведения см. в разделе Service Security and Access Rights.

Для каждой службы может быть только один запрос на уведомление.

[in] dwNotifyMask

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

[in] pNotifyBuffer

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

Не выполняйте несколько вызовов NotifyServiceStatusChange с одинаковым параметром буфера, пока функция обратного вызова из первого вызова не завершит работу с буфером или первый запрос уведомления не будет отменен. В противном случае нет гарантии, какую версию буфера получит функция обратного вызова.

Windows Vista: Адрес функции обратного вызова должен находиться в диапазоне адресов загруженного модуля. Таким образом, функция обратного вызова не может быть кодом, созданным во время выполнения (например, управляемым кодом, созданным JIT-компилятором), или машинным кодом, распакованным во время выполнения. Это ограничение было удалено в Windows Server 2008 и Windows Vista с пакетом обновления 1 (SP1).

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

Если функция выполняется успешно, возвращаемое значение будет ERROR_SUCCESS. Если служба помечена для удаления, возвращаемое значение ERROR_SERVICE_MARKED_FOR_DELETE и дескриптор службы должен быть закрыт. Если уведомление службы слишком сильно отстает от состояния системы, функция возвращает ERROR_SERVICE_NOTIFY_CLIENT_LAGGING. В этом случае клиент должен закрыть дескриптор для SCM, открыть новый дескриптор и снова вызвать эту функцию.

Если функция завершается сбоем, возвращаемое значение является одним из кодов системных ошибок.

Комментарии

Функцию NotifyServiceStatusChange можно использовать для получения уведомлений о приложениях-службах. Его нельзя использовать для получения уведомлений о службах драйверов.

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

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

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

Эффективнее вызывать NotifyServiceStatusChange из потока, выполняющего ожидание, чем для создания дополнительного потока.

После вызова функции обратного вызова вызывающий объект должен вызвать NotifyServiceStatusChange для получения дополнительных уведомлений. Обратите внимание, что некоторые функции в API Windows, включая NotifyServiceStatusChange и другие функции SCM, используют удаленные вызовы процедур (RPC). Эти функции могут выполнять операцию ожидания с оповещениями, поэтому они небезопасны для вызова из функции обратного вызова. Вместо этого функция обратного вызова должна сохранять параметры уведомления и выполнять любые дополнительные действия за пределами обратного вызова.

Чтобы отменить невыполненные уведомления, закройте дескриптор службы с помощью функции CloseServiceHandle . После успешного завершения CloseServiceHandle больше не будут помещаться в очередь api уведомлений. Если вызывающий поток завершает работу, не закрывая дескриптор службы или не дожидаясь создания APC, может произойти утечка памяти.

Требования

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

SERVICE_NOTIFY

SubscribeServiceChangeNotifications

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