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

Статья
08/23/2023

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

Синтаксис

ULONG EVNTAPI EventWrite(
  [in]           REGHANDLE              RegHandle,
  [in]           PCEVENT_DESCRIPTOR     EventDescriptor,
  [in]           ULONG                  UserDataCount,
  [in, optional] PEVENT_DATA_DESCRIPTOR UserData
);

Параметры

[in] RegHandle

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

[in] EventDescriptor

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

Важно!

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

[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, поэтому сборки выпуска обычно должны игнорировать код ошибки.

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

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

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

EventWrite задает идентификатор действия события в идентификаторе действия текущего потока. EventWrite не включает идентификатор связанного действия в событие. Чтобы указать другой идентификатор действия или добавить связанный идентификатор действия, используйте EventWriteTransfer.

EventWrite эквивалентен EventWriteEx с 0 для фильтра, 0 для флагов, NULL для ActivityId и NULL для RelatedActivityId.

Требования


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

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

EventActivityIdControl

EventRegister

EventWriteTransfer

EventWriteEx

Написание событий на основе манифеста.