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