Функция обратного вызова PENABLECALLBACK (evntprov.h)

  • Статья

Поставщики событий ETW при необходимости определяют функцию EnableCallback для получения уведомлений об изменениях конфигурации. Тип PENABLECALLBACK определяет указатель на эту функцию обратного вызова. EnableCallback — это заполнитель для имени функции, определяемой приложением.

Синтаксис

PENABLECALLBACK Penablecallback;

void Penablecallback(
  [in]           LPCGUID SourceId,
  [in]           ULONG IsEnabled,
  [in]           UCHAR Level,
  [in]           ULONGLONG MatchAnyKeyword,
                 ULONGLONG MatchAllKeyword,
  [in, optional] PEVENT_FILTER_DESCRIPTOR FilterData,
  [in, optional] PVOID CallbackContext
)
{...}

Параметры

[in] SourceId

GUID, указанный вызывающим объектом, который включает или отключит поставщик.

Значение берется из параметра SourceIdenableTraceEx или поля SourceIdENABLE_TRACE_PARAMETERS , передаваемого в EnableTraceEx2.

Примечание

SourceId — это значение сеанса, указанное в вызове API EnableTraceEx или EnableTraceEx2. Он может совпадать с идентификатором GUID сеанса.

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

[in] IsEnabled

Указывает ControlCode, соответствующий этому уведомлению. Может иметь одно из следующих значений:

Значение Значение
EVENT_CONTROL_CODE_DISABLE_PROVIDER (0) Ни в каких сеансах поставщик не включен.
EVENT_CONTROL_CODE_ENABLE_PROVIDER (1) Один или несколько сеансов включили поставщик.
EVENT_CONTROL_CODE_CAPTURE_STATE (2) Сеанс запрашивает, чтобы поставщик занот в журнал сведений о своем состоянии. Поставщик обычно отвечает, записывая события, содержащие состояние поставщика.

Примечание

Значение IsEnabled может отличаться от значения ControlCode , переданного в API EnableTrace , который активировал это событие. Например, если этот поставщик включен в два сеанса, а один сеанс отключает его путем вызова EnableTraceEx2(..., EVENT_CONTROL_CODE_DISABLE_PROVIDER, ...), поставщик получит уведомление с параметром EVENT_CONTROL_CODE_ENABLE_PROVIDERIsEnabled , так как поставщик по-прежнему включен другим сеансом.

Получив уведомление DISABLE_PROVIDER , поставщик может оптимизировать свою производительность, отключив все события. После получения уведомления ENABLE_PROVIDER поставщик должен включить запись событий. Он также может оптимизировать производительность, записывая значения фильтров Level, MatchAnyKeyword и MatchAllKeyword, а затем записывая только события, которые передают фильтры (как описано в примечаниях). После получения уведомления CAPTURE_STATE поставщик может предпринять любое действие, которое кажется целесообразным, обычно записывает события, описывающие конфигурацию или состояние компонента.

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

[in] Level

Значение типа , указывающее степень детализации событий, которые должен записать поставщик. При вызове с EVENT_CONTROL_CODE_ENABLE_PROVIDER кода элемента управления поставщик должен записать значение Level и пропустить события, в которых уровень детализации события больше записанного уровня, т. е. событие должно быть записано только в том случае, если

eventDescriptor.Level <= recorded.Level

Уровень в уведомлении — это максимум уровней, заданных контроллерами трассировки в вызовах EnableTrace, EnableTraceEx или EnableTraceEx2 с использованием GUID этого поставщика событий. Другими словами, если несколько сеансов записывают события от этого поставщика событий на разных уровнях детализации, параметру Level для уведомления EnableCallback будет присвоено значение самого высокого (самого подробного) уровня.

[in] MatchAnyKeyword

Значение битовой маски, указывающее категории событий, которые должен записать поставщик. При вызове с кодом элемента управления EVENT_CONTROL_CODE_ENABLE_PROVIDER поставщик должен записать значение MatchAnyKeyword и впоследствии пропускать события, в которых ключевое слово события не является нулевым и не имеет ни одного бита из записанного MatchAnyKeyword, т. е. событие должно быть записано только в том случае, если

eventDescriptor.Keyword == 0 || (eventDescriptor.Keyword & recorded.MatchAnyKeyword) != 0

MatchAnyKeyword в уведомлении — это объединение (ИЛИ) ключевых слов match-any-keywords (флагов включения), указанных контроллерами трассировки в вызовах EnableTrace, EnableTraceEx и EnableTraceEx2 для GUID этого поставщика событий. Иными словами, если несколько сеансов записывают события от этого поставщика событий с разными фильтрами match-any-ключевое слово, параметру MatchAnyKeyword уведомления EnableCallback будет присвоено побитовоеOR значение фильтров match-any-ключевое слово сеансов.

MatchAllKeyword

Значение битовой маски, указывающее категории событий, которые должен записать поставщик. При уведомлении с помощью EVENT_CONTROL_CODE_ENABLE_PROVIDER кода элемента управления поставщик должен записать значение MatchAllKeyword, а затем пропустить события, в которых ключевое слово события является ненулевым и не содержит все биты из записанного MatchAllKeyword, т. е. событие должно быть записано только в том случае, если

eventDescriptor.Keyword == 0 || (eventDescriptor.Keyword & recorded.MatchAllKeyword) == recorded.MatchAllKeyword

MatchAllKeyword в уведомлении — это дефъюнкция (AND) ключевых слов match-all-keywords, заданных контроллерами трассировки в вызовах EnableTraceEx и EnableTraceEx2 для GUID этого поставщика событий. Иными словами, если события от этого поставщика событий записываются несколькими сеансами с разными фильтрами match-all-ключевое слово, параметру MatchAllKeyword уведомления EnableCallback будет присвоено побитовоеAND значение фильтров match-all-ключевое слово сеансов.

[in, optional] FilterData

Указатель на EVENT_FILTER_DESCRIPTOR с данными фильтра для поставщика событий.

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

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

[in, optional] CallbackContext

Контекст для обратного вызова. Это значение параметра CallbackContext , которое использовалось, когда поставщик событий назывался EventRegister.

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

None

Remarks

Поставщики событий ETW, которым требуются уведомления об изменениях конфигурации, должны предоставлять указатель на свою реализацию EnableCallback при регистрации через EventRegister. Трассировка событий Windows вызывает функцию EnableCallback поставщика при изменении конфигурации сеанса трассировки, в который входит поставщик. Например, когда контроллер сеанса трассировки настраивает трассировку с помощью EnableTraceEx2 или останавливает трассировку с помощью ControlTrace, etW вызывает функцию EnableCallback поставщика с итоговой обновленной конфигурацией.

Примечание

Большинство поставщиков событий не реализуют EnableCallback напрямую. Вместо этого большинство поставщиков событий реализуются с помощью платформы ETW, которая предоставляет собственную реализацию EnableCallback и создает оболочку для вызовов EventRegister, EventWrite и EventUnregister. Например, можно написать манифест события , а затем использовать компилятор сообщений для создания кода C/C++ для событий, или использовать TraceLogging , чтобы избежать необходимости в манифесте. Платформа трассировки событий Windows обычно реализует функцию EnableCallback, которая записывает значения , MatchAnyKeywordи уведомленияLevel, а MatchAllKeyword платформа автоматически использует записанные значения для фильтрации событий. Платформа трассировки событий Windows обычно поддерживает вызов обратного вызова, предоставляемого пользователем, если пользователю требуется пользовательская обработка уведомлений. Например, TraceLoggingProvider.h позволяет указать обратный вызов уведомления с помощью TraceLoggingRegisterEx.

Важно!

Функция EnableCallback поставщика должна быть максимально простой. Он должен записывать необходимые сведения и быстро возвращать их. Долго выполняющаяся функция обратного вызова может привести к задержкам в API управления сеансами ETW, таких как EnableTraceEx2 или ControlTrace. Функция обратного вызова не должна выполнять действия, требующие блокировки загрузчика процесса, т. е. она не должна напрямую или косвенно вызывать LoadLibrary или FreeLibrary. Функция обратного вызова не должна блокировать блокировки. Функция обратного вызова может вызвать взаимоблокировку, если она блокирует блокировки или вызывает любые API управления сеансом ETW, такие как StartTrace, ControlTrace или EnableTrace.

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

Обратите внимание, что отслеживание фильтра не требуется для правильной работы поставщика: трассировка событий Windows предоставляет функции EventEnabled и EventProviderEnabled , которые может использовать поставщик, а API EventWrite трассировки событий Windows будут автоматически игнорировать все отключенные события. Однако отслеживание фильтра, реализованного поставщиком, может быть более эффективным, чем вызовы EventEnabled или EventProviderEnabled.

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

Значение уровня , которое трассировка событий Windows передает обратному вызову, является самым высоким (наиболее подробным) уровнем, заданным для этого поставщика событий любым запущенным сеансом трассировки. Например, если сеанс A включил этот поставщик для предупреждений (уровень 3), а затем сеанс B включает поставщик для критических событий (уровня 1), значение уровня для обратного вызова будет равно 3, а не 1.

Аналогичным образом значения MatchAnyKeyword и MatchAllKeyword являются составными значениями, вычисленными на основе конфигурации всех сеансов, в которых включен поставщик событий. MatchAnyKeyword — это ИЛИ параметров EnableFlags/MatchAnyKeyword сеансов. MatchAllKeyword — это И параметров MatchAllKeyword сеансов.

Если функция EnableCallback поставщика захватила состояние Enabled, Level, MatchAnyKeyword и MatchAllKeyword поставщика, поставщик может определить, следует ли записывать событие, с помощью следующей функции:

BOOL MyProviderEventEnabled(
    _In_ const MY_PROVIDER_STATE* pProvider,
    _In_ const EVENT_DESCRIPTOR* pEvent)
{
    return
        pProvider->Enabled &&
        pEvent->Level <= pProvider->Level &&
        (pEvent->Keyword == 0 || (
            (pEvent->Keyword & pProvider->MatchAnyKeyword) != 0 &&
            (pEvent->Keyword & pProvider->MatchAllKeyword) == pProvider->MatchAllKeyword
        ));
}

Требования

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

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

EventRegister

EnableTrace

EnableTraceEx2