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

Статья
08/23/2023

Функция ProcessTrace доставляет события из одного или нескольких сеансов обработки трассировки ETW потребителю.

Синтаксис

ETW_APP_DECLSPEC_DEPRECATED ULONG WMIAPI ProcessTrace(
  [in] PTRACEHANDLE HandleArray,
  [in] ULONG        HandleCount,
  [in] LPFILETIME   StartTime,
  [in] LPFILETIME   EndTime
);

Параметры

[in] HandleArray

Указатель на массив дескрипторов сеанса обработки трассировки, полученных из предыдущих вызовов функции OpenTrace .

Массив может содержать до 64 дескрипторов для сеансов обработки файлов или один дескриптор для сеанса обработки в режиме реального времени. Массив не может содержать как дескрипторы сеанса обработки файлов, так и дескрипторы сеанса обработки в режиме реального времени.

[in] HandleCount

Количество элементов в HandleArray.

[in] StartTime

Указатель на необязательную структуру FILETIME , которая указывает начальный период времени, в течение которого требуется получать события. Функция не доставляет события с метками времени, предшествующими StartTime.

[in] EndTime

Указатель на необязательную структуру FILETIME , которая указывает конечный период времени, в течение которого требуется получать события. Функция не доставляет события с метками времени после EndTime.

Windows Server 2003: Это значение игнорируется для доставки событий в режиме реального времени.

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

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

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

ERROR_BAD_LENGTH

Значение HandleCount является недопустимым или число дескрипторов больше 64.
ERROR_INVALID_HANDLE

Элемент HandleArray не является допустимым дескриптором сеанса трассировки событий.
ERROR_INVALID_TIME

EndTime меньше, чем StartTime.
ERROR_INVALID_PARAMETER

HandleArray имеет значение NULL, содержит как сеансы обработки файлов, так и сеансы обработки в режиме реального времени или содержит несколько сеансов обработки в режиме реального времени.
ERROR_NOACCESS

В одной из функций обратного вызова, получающей события, возникло исключение.
ERROR_CANCELLED

Указывает, что потребитель отменил обработку, возвращая значение FALSE в функции BufferCallback .
ERROR_WMI_INSTANCE_NOT_FOUND

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

Потребители трассировки вызывают эту функцию для обработки событий из одного или нескольких сеансов обработки трассировки. Эта функция блокируется до завершения обработки.

Перед вызовом ProcessTrace используйте OpenTrace , чтобы открыть дескрипторы для сеансов обработки трассировки.

Функция ProcessTrace доставляет события из сеансов, вызывая функции обратного вызова BufferCallback, EventCallback и EventRecordCallback потребителя.

Функция ProcessTrace пытается доставить события по порядку на основе метки времени события (т. е. пытается доставить события в самые старые). В некоторых случаях ProcessTrace может доставлять события не по порядку.

Если часы, используемые для меток времени событий, корректируются назад во время сбора трассировки, порядок доставки событий непредсказуем. Чтобы избежать этой проблемы, используйте часы QPC вместо системных часов времени при сборе трассировки.
Если на разных ЦП собираются несколько событий с одной и той же меткой времени, порядок доставки событий непредсказуем.
Если событие имеет недопустимую метку времени (например, из-за повреждения файла), порядок доставки этого события и других событий в трассировке может быть непредсказуемым.

Функция ProcessTrace блокирует поток, пока он не доставляет все события, функция BufferCallback возвращает значение FALSE или вызывается метод CloseTrace. Кроме того, если потребитель использует события в режиме реального времени, функция ProcessTrace возвращается после того, как контроллер останавливает сеанс трассировки. (Обратите внимание, что перед возвратом функции может возникнуть задержка в несколько секунд.)

Windows Server 2003: Метод CloseTrace можно вызвать только после возврата ProcessTrace .

Примеры

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

Требования


Минимальная версия клиента	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