Поделиться через


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

Поставщик событий на основе 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

    Выполняется одно из следующих условий.

  • ERROR_MORE_DATA

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

Комментарии

Поставщики трассировки событий Windows на основе MOF вызывают эту функцию.

Примечание

Большинство разработчиков не будут вызывать эту функцию. Этот 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

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

EVENT_TRACE_HEADER

EnableTrace

RegisterTraceGuids

TraceEventInstance