Функция EventEnabled (evntprov.h)

Статья
03/11/2023

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

Возвращает значение FALSE , если трассировка событий Windows может быстро определить, что ни один сеанс не прослушивает указанное событие от заданного поставщика. В противном случае возвращает значение TRUE.

Синтаксис

BOOLEAN EVNTAPI EventEnabled(
  [in] REGHANDLE          RegHandle,
  [in] PCEVENT_DESCRIPTOR EventDescriptor
);

Параметры

[in] RegHandle

Дескриптор регистрации поставщика. Дескриптор поступает из EventRegister.

Если RegHandle имеет значение NULL, EventEnabled возвращает значение FALSE.

[in] EventDescriptor

EVENT_DESCRIPTOR , предоставляющий сведения, которые будут использоваться для определения того, включено ли событие. Сюда входят уровень события (серьезность) и ключевое слово (категории).

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

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

Этот API предоставляет простой способ определить, включено ли событие (т. е. заинтересованы ли какие-либо сеансы потребителя события в получении события) на основе дескриптора поставщика и дескриптора события.

Примечание

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

Этот API предоставляет функциональные возможности, аналогичные функциям, предоставляемым EventProviderEnabled. Если поставщик имеет доступ к полному EVENT_DESCRIPTOR события, поставщик должен использовать EventEnabled. Если поставщик имеет доступ только к уровню и ключевому слову события, поставщик должен использовать EventProviderEnabled.

Большинство поставщиков событий не будут вызывать EventEnabled напрямую:

API EventWrite включают собственный тест EventEnabled и возвращаются немедленно, если событие не включено.
Большинство поставщиков ETW используют платформу ETW (например, манифесты или TraceLogging) вместо прямого вызова EventWrite или EventEnabled. Платформы трассировки событий Windows обычно предоставляют собственный API с поддержкой событий, который следует использовать вместо вызова EventEnabled.
Реализации платформы трассировки событий Windows обычно проверка собственное состояние поставщика, а не вызов EventEnabled.

Требования


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

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

EventProviderEnabled

EVENT_DESCRIPTOR