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

Статья
08/23/2023

Функция OpenTrace открывает дескриптор обработки трассировки ETW для использования событий из сеанса трассировки ETW в режиме реального времени или файла журнала ETW.

Синтаксис

TRACEHANDLE WMIAPI OpenTraceA(
  [in, out] PEVENT_TRACE_LOGFILEA Logfile
);

Параметры

[in, out] Logfile

Указатель на структуру EVENT_TRACE_LOGFILE . Структура определяет источник, из которого будут использоваться события (из файла журнала ETW или сеанса ETW в режиме реального времени), а также обратные вызовы, которые потребитель хочет использовать для получения событий. При успешном выполнении OpenTrace обновит структуру данными из открытого файла или сеанса.

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

Если функция выполняется успешно, она возвращает дескриптор обработки трассировки. Дескриптор должен быть закрыт с помощью CloseTrace.

Если функция завершается сбоем, она возвращает INVALID_PROCESSTRACE_HANDLE. (INVALID_PROCESSTRACE_HANDLE эквивалентно (UINT64)UINTPTR_MAX.)

Примечание

До Windows Vista openTrace возвращался UINT64_MAX в случае сбоя. Если ваш код поддерживает как старые операционные системы (Windows XP или Windows Server 2003), так и более новые версии Windows (Windows Vista и более поздние версии), необходимо определить операционную систему, в которой выполняется, и сравнить возвращаемое значение с соответствующим значением.

Операционная система	Тип процесса	Значение, указывающее на сбой
До Windows Vista	32- или 64-разрядная версия	`0XFFFFFFFFFFFFFFFF` = `UINT64_MAX`
Windows Vista или более поздней версии	32-разрядная система	`0x00000000FFFFFFFF` = `(UINT64)UINTPTR_MAX`
Windows Vista или более поздней версии	64-разрядная система	`0XFFFFFFFFFFFFFFFF` = `(UINT64)UINTPTR_MAX`

В случае сбоя функции можно использовать функцию GetLastError для получения расширенных сведений об ошибке. Ниже приведены некоторые распространенные ошибки и их причины.

ERROR_INVALID_PARAMETER

Параметр Logfile имеет значение NULL.
ERROR_BAD_PATHNAME

Если вы не указали элемент LoggerNameEVENT_TRACE_LOGFILE, необходимо указать допустимое имя файла журнала.
ERROR_ACCESS_DENIED

Только пользователи с правами администратора, пользователи в группе Пользователи журнала производительности и службы под управлением LocalSystem, LocalService, NetworkService могут использовать события в режиме реального времени. Чтобы предоставить ограниченному пользователю возможность использовать события в режиме реального времени, добавьте его в группу Пользователи журнала производительности.

Windows XP и Windows 2000: Любой пользователь может использовать события в режиме реального времени.

После вызова OpenTrace вызовите функцию ProcessTrace для обработки событий. Завершив обработку событий, вызовите функцию CloseTrace , чтобы закрыть дескриптор обработки трассировки.

Примеры

Пример использования OpenTrace см. в статье Использование TdhFormatProperty для использования данных о событиях.

Примечание

Заголовок evntrace.h определяет OpenTrace в качестве псевдонима, который автоматически выбирает версию ANSI или Юникод этой функции на основе определения константы препроцессора UNICODE. Сочетание использования псевдонима, не зависящий от кодировки, с кодом, не зависящим от кодировки, может привести к несоответствиям, которые приводят к ошибкам компиляции или среды выполнения. Дополнительные сведения см. в разделе Соглашения для прототипов функций.

Требования

Требование	Значение
Минимальная версия клиента	Windows 2000 Профессиональная [классические приложения \| Приложения UWP]
Минимальная версия сервера	Windows 2000 Server [классические приложения \| Приложения UWP]
Целевая платформа	Windows
Header	evntrace.h
Библиотека	Sechost.lib в Windows 8.1 и Windows Server 2012 R2; Advapi32.lib в Windows 8, Windows Server 2012, Windows 7, Windows Server 2008 R2, Windows Server 2008, Windows Vista и Windows XP
DLL	Sechost.dll в Windows 8.1 и Windows Server 2012 R2; Advapi32.dll в Windows 8, Windows Server 2012, Windows 7, Windows Server 2008 R2, Windows Server 2008, Windows Vista и Windows XP

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

CloseTrace

EVENT_TRACE_LOGFILE

ProcessTrace

Share via