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

Функция 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

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

Значение Значение
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 [только классические приложения]
Целевая платформа Windows
Header winsvc.h (включая Windows.h)
Библиотека Advapi32.lib
DLL Advapi32.dll

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

SERVICE_NOTIFY

SubscribeServiceChangeNotifications

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