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

Записывает событие трассировки событий 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 сведениями о событиях (метаданными), включая идентификатор, версию, уровень, ключевое слово, канал, код операции и задачу.

[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.

Требования

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

EventActivityIdControl

EventRegister

EventWriteTransfer

EventWriteEx

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