Функция TraceEventInstance (evntrace.h)
Поставщик событий на основе 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 структуры.
Комментарии
Поставщики трассировки событий Windows на основе MOF вызывают эту функцию.
Примечание
Большинство разработчиков не будут вызывать эту функцию. Этот 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 |