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

Статья
08/23/2023

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

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

Синтаксис

ULONG WMIAPI TraceEventInstance(
  [in] TRACEHANDLE            TraceHandle,
  [in] PEVENT_INSTANCE_HEADER EventTrace,
  [in] PEVENT_INSTANCE_INFO   InstInfo,
  [in] PEVENT_INSTANCE_INFO   ParentInstInfo
);

Параметры

[in] TraceHandle

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

[in] EventTrace

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

Размер
Flags
RegHandle

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

Class.Type
Class.Level

Для трассировки иерархических связей между связанными событиями также задайте элемент ParentRegHandle .

[in] InstInfo

Указатель на структуру EVENT_INSTANCE_INFO , которая содержит дескриптор регистрации для этого класса трассировки событий и идентификатор экземпляра. Используйте функцию CreateTraceInstanceId для инициализации структуры.

[in] ParentInstInfo

Указатель на структуру EVENT_INSTANCE_INFO , которая содержит дескриптор регистрации для родительского класса трассировки событий и его идентификатор экземпляра. Используйте функцию CreateTraceInstanceId для инициализации структуры. Установите значение NULL , если не выполняется трассировка иерархической связи.

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

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

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

ERROR_INVALID_FLAGS

Элемент FlagsEVENT_INSTANCE_HEADER не содержит WNODE_FLAG_TRACED_GUID.
ERROR_OUTOFMEMORY

Недостаточно памяти для завершения вызова функции. Причины этого кода ошибки описаны в следующем разделе примечаний.
ERROR_INVALID_PARAMETER

Выполняется одно из следующих условий.
- EventTrace имеет значение NULL.
- pInstInfo имеет значение NULL.
- Элементы pInstInfo имеют значение NULL.
- TraceHandle имеет значение NULL.
- Неправильный элемент SizeEVENT_INSTANCE_HEADER .
ERROR_INVALID_HANDLE

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

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

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

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

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

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

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

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

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

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

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

Windows XP: Неправильно работает.

Примеры

Пример создания связанных наборов событий с помощью CreateTraceInstanceId и TraceEventInstance см. в разделе Трассировка экземпляров событий.

Требования


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