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

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

Синтаксис

ETW_APP_DECLSPEC_DEPRECATED ULONG WMIAPI ProcessTrace(
  [in] PROCESSTRACE_HANDLE *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 меньше начального времени.

• ERROR_INVALID_PARAMETER

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

• ERROR_NOACCESS

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

• ERROR_CANCELLED

  Указывает, что потребитель отменил обработку, возвращая ЗНАЧЕНИЕ FALSE в функции BufferCallback .

• ERROR_WMI_INSTANCE_NOT_FOUND

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

Замечания

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

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

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

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

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

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

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

Примеры

Пример использования ProcessTrace см. в разделе Using TdhFormatProperty to Using Event Data.

Требования

См. также

BufferCallback

EventCallback

EventRecordCallback

OpenTrace