Функция EvtSubscribe (winevt.h)

Статья
08/27/2023

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

Синтаксис

EVT_HANDLE EvtSubscribe(
  [in] EVT_HANDLE             Session,
  [in] HANDLE                 SignalEvent,
  [in] LPCWSTR                ChannelPath,
  [in] LPCWSTR                Query,
  [in] EVT_HANDLE             Bookmark,
  [in] PVOID                  Context,
  [in] EVT_SUBSCRIBE_CALLBACK Callback,
  [in] DWORD                  Flags
);

Параметры

[in] Session

Удаленный дескриптор сеанса, который возвращает функция EvtOpenSession . Установите значение NULL , чтобы подписаться на события на локальном компьютере.

[in] SignalEvent

Дескриптор объекта события, о котором служба будет сообщать, когда будут доступны новые события, соответствующие условиям запроса. Этот параметр должен иметь значение NULL, если параметр Callback не равен NULL.

[in] ChannelPath

Имя Администратор или операционный канал, содержащий события, на которые вы хотите подписаться (вы не можете подписаться на каналы аналитики или отладки). Путь является обязательным, если параметр Query содержит запрос XPath; Путь игнорируется, если параметр Query содержит структурированный XML-запрос.

[in] Query

Запрос, указывающий типы событий, возвращаемых службой подписки. Можно указать запрос XPath 1.0 или структурированный XML-запрос. Если XPath содержит более 20 выражений, используйте структурированный XML-запрос. Чтобы получить все события, задайте для этого параметра значение NULL или "*".

[in] Bookmark

Дескриптор закладки, определяющий начальную точку для подписки. Чтобы получить дескриптор закладки, вызовите функцию EvtCreateBookmark . Этот параметр необходимо задать, если параметр Flags содержит флаг EvtSubscribeStartAfterBookmark; в противном случае — NULL.

[in] Context

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

[in] Callback

Указатель на функцию обратного вызова EVT_SUBSCRIBE_CALLBACK, которая будет получать события подписки. Этот параметр должен иметь значение NULL, если параметр SignalEvent не равен NULL.

[in] Flags

Один или несколько флагов, указывающих, когда следует начать подписку на события. Например, если указать EvtSubscribeStartAtOldestRecord, служба получит все текущие и будущие события, соответствующие условиям запроса; Однако если указать EvtSubscribeToFutureEvents, служба возвращает только будущие события, соответствующие условиям запроса. Возможные значения см. в перечислении EVT_SUBSCRIBE_FLAGS .

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

Дескриптор подписки в случае успешного выполнения; в противном случае — NULL. Если функция возвращает значение NULL, вызовите функцию GetLastError , чтобы получить код ошибки. По завершении необходимо вызвать функцию EvtClose с дескриптором подписки.

Существует две модели подписки: модель опроса и модель отправки. В модели отправки вы реализуете обратный вызов подписки и задаете для параметра Callback свою реализацию. Служба будет вызывать обратный вызов для каждого события, соответствующего условиям запроса (или при возникновении ошибки).

В модели опроса создается объект события, который сообщает служба. При получении сигнала вы вызываете функцию EvtNext , используя дескриптор подписки для перечисления событий. Необходимо вызывать функцию EvtClose для каждого перечисленного события. Затем вы сбрасываете объект и ожидаете, пока служба снова сообщит. Этот процесс повторяется до тех пор, пока вы не отмените подписку.

Примеры

Пример использования этой функции см. в разделе Подписка на события.

Требования


Минимальная версия клиента	Windows Vista [только классические приложения]
Минимальная версия сервера	Windows Server 2008 [только классические приложения]
Целевая платформа	Windows
Header	winevt.h
Библиотека	Wevtapi.lib
DLL	Wevtapi.dll

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

EVT_SUBSCRIBE_CALLBACK

EvtQuery