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

Статья
02/27/2024

Записывает событие трассировки событий Windows с идентификатором действия, необязательным идентификатором связанного действия, фильтрами сеанса и специальными параметрами.

Синтаксис

ULONG EVNTAPI EventWriteEx(
  [in]           REGHANDLE              RegHandle,
  [in]           PCEVENT_DESCRIPTOR     EventDescriptor,
  [in]           ULONG64                Filter,
  [in]           ULONG                  Flags,
  [in, optional] LPCGUID                ActivityId,
  [in, optional] LPCGUID                RelatedActivityId,
  [in]           ULONG                  UserDataCount,
  [in, optional] PEVENT_DATA_DESCRIPTOR UserData
);

Параметры

[in] RegHandle

Дескриптор регистрации поставщика. Дескриптор поступает из EventRegister. Созданное событие будет использовать Идентификатор поставщика, связанный с дескриптором.

[in] EventDescriptor

EVENT_DESCRIPTOR сведениями о событиях (метаданными), включая идентификатор, версию, уровень, ключевое слово, канал, код операции и задачу.

Важно!

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

[in] Filter

Значение 64-разрядной битовой маски. Каждый бит набора указывает, что это событие должно быть исключено из определенного сеанса трассировки.

Параметр Filter используется с поставщиками событий, которые выполняют настраиваемую фильтрацию событий на основе FilterData из EnableCallback.

Установите для параметра Фильтр значение 0, если вы не поддерживаете настраиваемые фильтры событий или если событие должно быть записано во все сеансы трассировки. В противном случае задайте для параметра Filter значение побитового ИЛИ идентификаторов сеансов, которые НЕ должны получать событие.

[in] Flags

Установите для параметра Флаги значение 0 для обычной обработки событий.

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

EVENT_WRITE_FLAG_INPRIVATE (0x2)

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

[in, optional] ActivityId

Необязательный указатель на 128-разрядный идентификатор действия для этого события. Если это значение не равно NULL, EventWriteEx будет использовать указанное значение для идентификатора действия события. Если это значение равно NULL, EventWriteEx будет использовать идентификатор действия текущего потока.

Средства обработки трассировки могут использовать идентификатор действия события для организации событий в группы, называемые действиями. Дополнительные сведения об идентификаторе действия см. в разделе EventActivityIdControl.

[in, optional] RelatedActivityId

Необязательный указатель на 128-разрядный идентификатор действия, который является родительским для действия этого события. Если это значение не равно NULL, EventWriteEx будет использовать указанное значение для идентификатора связанного с событием действия. Если это значение равно NULL, событие не будет иметь связанного идентификатора действия. Идентификатор связанного действия обычно задается для события START действия (первое событие действия, зарегистрированное с помощью Opcode = START).

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

[in] UserDataCount

Число EVENT_DATA_DESCRIPTOR структур в UserData. Максимальное число — 128.

[in, optional] UserData

Массив userDataCountEVENT_DATA_DESCRIPTOR структур, описывающих данные, которые должны быть включены в событие. UserData может иметь значение NULL , если UserDataCount равно нулю.

Каждый EVENT_DATA_DESCRIPTOR описывает один блок памяти для включения в событие. Указанные блоки будут сцеплены в порядке без заполнения или выравнивания для формирования содержимого события. При использовании декодирования на основе манифеста содержимое события должно соответствовать макету, указанному в шаблоне, связанном с событием в манифесте.

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

Возвращает ERROR_SUCCESS в случае успешного выполнения или кода ошибки. Возможные коды ошибок:

ERROR_INVALID_PARAMETER: один или несколько параметров недопустимы.
ERROR_INVALID_HANDLE. Недопустимый дескриптор регистрации поставщика.
ERROR_ARITHMETIC_OVERFLOW: размер события больше допустимого максимума (64 КБ — заголовок).
ERROR_MORE_DATA. Размер буфера сеанса слишком мал для события.
ERROR_NOT_ENOUGH_MEMORY. Происходит, когда заполненные буферы пытаются выполнить запись на диск, но операции ввода-вывода на диске выполняются недостаточно быстро. Это происходит при медленном выполнении диска и интенсивном трафике событий. В конечном итоге отсутствуют свободные (пустые) буферы, и событие удаляется.
STATUS_LOG_FILE_FULL. Файл воспроизведения в режиме реального времени заполнен. События не регистрируются в сеансе, пока потребитель в режиме реального времени не будет использовать события из файла воспроизведения.

Код ошибки в основном предназначен для использования в сценариях отладки и диагностики. Большая часть рабочего кода должна продолжать выполняться и сообщать о событиях, даже если не удалось написать событие трассировки событий Windows, поэтому сборки выпуска обычно должны игнорировать код ошибки.

Большинство поставщиков событий не вызывают EventWriteEx напрямую. Вместо этого большинство поставщиков событий реализуются с помощью платформы ETW, которая заключает вызовы EventRegister, EventWriteEx и EventUnregister. Например, можно написать манифест события , а затем использовать компилятор сообщений для создания кода C/C++ для событий, или использовать TraceLogging , чтобы избежать необходимости в манифесте.

EventWriteEx перенаправит событие в соответствующие сеансы трассировки на основе ProviderId (определенного из RegHandle), Level, Ключевого слова и других характеристик события. Если сеансы трассировки не записывают это событие, эта функция не выполняет никаких действий и возвращает ERROR_SUCCESS.

Чтобы уменьшить влияние на производительность событий, которые не записываются ни в одном сеансе трассировки, можно вызвать EventEnabled , чтобы определить, записывает ли какой-либо сеанс трассировки событие перед подготовкой данных и вызовом EventWriteEx.

Поставщик может определить фильтры, которые сеанс использует для фильтрации событий на основе данных о событиях. Основные фильтры основаны на уровне и ключевых словах. Поставщики событий могут поддерживать более сложные фильтры. Поставщик событий может получать сведения о фильтре из параметра FilterDataобъекта EnableCallback. Поставщик может оценить фильтр и использовать параметр Filterобъекта EventWriteEx , чтобы указать, что некоторые сеансы трассировки не прошли фильтр и поэтому не должны получать событие.

Требования

Требование	Значение
Минимальная версия клиента	Windows 7 [классические приложения \| Приложения UWP]
Минимальная версия сервера	Windows Server 2008 R2 [классические приложения \| Приложения UWP]
Целевая платформа	Windows
Header	evntprov.h
Библиотека	Advapi32.lib
DLL	Advapi32.dll