Функция EventWriteTransfer (evntprov.h)
Записывает событие трассировки событий Windows с идентификатором действия и необязательным идентификатором связанного действия.
Синтаксис
ULONG EVNTAPI EventWriteTransfer(
[in] REGHANDLE RegHandle,
[in] PCEVENT_DESCRIPTOR EventDescriptor,
[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, optional] ActivityId
Необязательный указатель на 128-разрядный идентификатор действия для этого события. Если это значение не равно NULL, EventWriteTransfer будет использовать указанное значение для идентификатора действия события. Если это значение равно NULL, EventWriteTransfer будет использовать идентификатор действия текущего потока.
Средства обработки трассировки могут использовать идентификатор действия события для организации событий в группы, называемые действиями. Дополнительные сведения об идентификаторе действия см. в разделе EventActivityIdControl.
[in, optional] RelatedActivityId
Необязательный указатель на 128-разрядный идентификатор действия, который является родительским для действия этого события. Если это значение не равно NULL, EventWriteTransfer будет использовать указанное значение для идентификатора связанного действия события. Если это значение равно 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, поэтому сборки выпуска обычно должны игнорировать код ошибки.
Комментарии
Большинство поставщиков событий не вызывают EventWriteTransfer напрямую. Вместо этого большинство поставщиков событий реализуются с помощью платформы ETW, которая заключает вызовы EventRegister, EventWriteTransfer и EventUnregister. Например, можно написать манифест события , а затем использовать компилятор сообщений для создания кода C/C++ для событий, или использовать TraceLogging , чтобы избежать необходимости в манифесте.
EventWriteTransfer перенаправит событие в соответствующие сеансы трассировки на основе ProviderId (определенного из RegHandle), level, ключевого слова и других характеристик события. Если сеансы трассировки не записывают это событие, эта функция не выполняет никаких действий и возвращает ERROR_SUCCESS.
Чтобы уменьшить влияние событий, которые не записываются ни в одном сеансе трассировки, можно вызвать EventEnabled , чтобы определить, записывает ли какой-либо сеанс трассировки событие перед подготовкой данных и вызовом EventWriteTransfer.
EventWriteTransfer эквивалентно EventWriteEx с 0 для фильтра и 0 для флагов.
Требования
| Требование | Значение |
|---|---|
| Минимальная версия клиента | Windows Vista [классические приложения | Приложения UWP] |
| Минимальная версия сервера | Windows Server 2008 [классические приложения | Приложения UWP] |
| Целевая платформа | Windows |
| Header | evntprov.h |
| Библиотека | Advapi32.lib |
| DLL | Advapi32.dll |