Функция TraceEvent (evntrace.h)

Статья
08/23/2023

Поставщик событий на основе RegisterTraceGuids ("Классическая") использует функцию TraceEvent для отправки структурированного события в сеанс трассировки событий.

Синтаксис

ULONG WMIAPI TraceEvent(
  [in] TRACEHANDLE         TraceHandle,
  [in] PEVENT_TRACE_HEADER EventTrace
);

Параметры

[in] TraceHandle

Обработка сеанса трассировки событий, который записывает событие. Поставщик получает дескриптор при вызове функции GetTraceLoggerHandle в реализации ControlCallback .

[in] EventTrace

Указатель на структуру EVENT_TRACE_HEADER . Данные, относящиеся к событиям, при необходимости добавляются в структуру. Наибольшее событие, которое можно записать в журнал, немного меньше 64K. Необходимо указать значения для следующих элементов структуры EVENT_TRACE_HEADER .

Размер
Guid или GuidPtr
Flags

В зависимости от сложности информации, которую предоставляет поставщик, следует также указать значения для следующих членов.

Class.Type
Class.Level

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

Если функция выполнена успешно, возвращаемое значение будет ERROR_SUCCESS.

Если функция завершается сбоем, возвращаемое значение является одним из кодов системных ошибок. Ниже приведены некоторые распространенные ошибки и их причины.

ERROR_INVALID_FLAG_NUMBER

Неправильный элемент Flags структуры EVENT_TRACE_HEADER .
ERROR_INVALID_HANDLE

TraceHandle недопустим или указывает дескриптор сеанса средства ведения журнала ядра NT.
ERROR_NOT_ENOUGH_MEMORY

Сеанс исчерпал свободные буфера для записи. Это может произойти при высокой частоте событий из-за перегрузки дисковой подсистемы или недостаточного количества буферов. Вместо блокировки, пока не станет доступно больше буферов, TraceEvent отменяет событие.

Следует увеличить количество и размер буферов для сеанса, уменьшить количество записанных событий или их размер.

Windows 2000: Не поддерживается.
ERROR_OUTOFMEMORY

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

Выполняется одно из следующих условий.
- TraceHandle имеет значение NULL.
- EventTrace имеет значение NULL.
- Неправильный элемент Sizeструктуры EVENT_TRACE_HEADER .
ERROR_MORE_DATA

Данные из одного события не могут охватывать несколько буферов. Событие трассировки ограничено размером буфера сеанса трассировки событий за вычетом размера структуры EVENT_TRACE_HEADER .

Большинство разработчиков не будут вызывать эту функцию. Этот API поддерживает ETW на основе MOF, но трассировка событий windows на основе MOF является устаревшей в пользу трассировки событий windows на основе манифеста. Кроме того, большинство поставщиков на основе MOF используют функции-оболочки, созданные MC.exe, вместо прямого вызова API трассировки событий Windows.

Прежде чем поставщик сможет вызвать эту функцию, поставщик

Необходимо вызвать функцию RegisterTraceGuids , чтобы зарегистрировать себя и класс трассировки событий.
Должен быть включен. Контроллер вызывает функцию EnableTrace для включения поставщика.

Событие записывается в файл журнала, отправляется потребителям трассировки событий в режиме реального времени или и то, и другое. Элемент LogFileModeструктуры EVENT_TRACE_PROPERTIES , передаваемой в StartTrace , определяет, куда отправляется событие.

События трассировки записываются в том порядке, в котором они происходят.

Для трассировки набора связанных событий используйте функцию TraceEventInstance .

В Windows Vista для ведения журнала событий следует использовать функцию EventWrite .

Примеры

Пример использования TraceEvent см. в разделе Трассировка событий.

Требования


Минимальная версия клиента	Windows 2000 Professional [только классические приложения]
Минимальная версия сервера	Windows 2000 Server [только классические приложения]
Целевая платформа	Windows
Header	evntrace.h
Библиотека	Advapi32.lib
DLL	Advapi32.dll

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