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

Статья
08/27/2023

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

Синтаксис

DWORD NotifyServiceStatusChangeW(
  [in] SC_HANDLE        hService,
  [in] DWORD            dwNotifyMask,
  [in] PSERVICE_NOTIFYW pNotifyBuffer
);

Параметры

[in] hService

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

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

[in] dwNotifyMask

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

Ценность	Значение
SERVICE_NOTIFY_CREATED 0x00000080	Сообщите о создании службы. Параметр hService должен быть дескриптором SCM.
SERVICE_NOTIFY_CONTINUE_PENDING 0x00000010	Сообщите, когда служба будет продолжаться. Параметр hService должен быть дескриптором службы.
SERVICE_NOTIFY_DELETE_PENDING 0x00000200	Сообщите, когда приложение указало службу в вызове функции DeleteService. Приложение должно закрыть все дескрипторы службы, чтобы его можно было удалить. Параметр hService должен быть дескриптором службы.
SERVICE_NOTIFY_DELETED 0x00000100	Сообщите об удалении службы. Приложение не может получать это уведомление, если он имеет открытый дескриптор для службы. Параметр hService должен быть дескриптором SCM.
SERVICE_NOTIFY_PAUSE_PENDING 0x00000020	Сообщите о приостановке работы службы. Параметр hService должен быть дескриптором службы.
SERVICE_NOTIFY_PAUSED 0x00000040	Сообщите, когда служба приостановлена. Параметр hService должен быть дескриптором службы.
SERVICE_NOTIFY_RUNNING 0x00000008	Сообщите о выполнении службы. Параметр hService должен быть дескриптором службы.
SERVICE_NOTIFY_START_PENDING 0x00000002	Сообщите о запуске службы. Параметр hService должен быть дескриптором службы.
SERVICE_NOTIFY_STOP_PENDING 0x00000004	Сообщите об остановке службы. Параметр hService должен быть дескриптором службы.
SERVICE_NOTIFY_STOPPED 0x00000001	Сообщите, когда служба остановлена. Параметр hService должен быть дескриптором службы.

[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, может возникнуть утечка памяти.

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

Заметка

Заголовок winsvc.h определяет NotifyServiceStatusChange как псевдоним, который автоматически выбирает версию ANSI или Юникод этой функции на основе определения константы препроцессора ЮНИКОДа. Сочетание использования псевдонима, нейтрального для кодирования, с кодом, не зависящим от кодирования, может привести к несоответствиям, которые приводят к ошибкам компиляции или среды выполнения. Дополнительные сведения см. в соглашениях о прототипах функций.

Требования

Требование	Ценность
минимальные поддерживаемые клиентские	Windows Vista [только классические приложения]
минимальный поддерживаемый сервер	Windows Server 2008 [только классические приложения]
целевая платформа	Виндоус
заголовка	winsvc.h (включая Windows.h)
библиотеки	Advapi32.lib
DLL	Advapi32.dll

См. также

SERVICE_NOTIFY

SubscribeServiceChangeNotifications

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

Поделиться через