Share via

processTrace 函数 (evntrace.h)

  • 项目

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

    指示使用者在其 BufferCallback 函数中返回 FALSE 取消处理。

  • ERROR_WMI_INSTANCE_NOT_FOUND

    尝试从中实时使用事件的跟踪收集会话未运行或未启用实时跟踪模式。

备注

跟踪使用者调用此函数来处理来自一个或多个跟踪处理会话的事件。 此函数在处理结束之前会阻止。

在调用 ProcessTrace 之前，请使用 OpenTrace 打开句柄以跟踪处理会话。

ProcessTrace 函数通过调用使用者的 BufferCallback、EventCallback 和 EventRecordCallback 回调函数来传递会话中的事件。

ProcessTrace 函数尝试根据事件的时间戳 (按顺序传递事件，即尝试将最早的事件传递到最新的) 。 在某些情况下， ProcessTrace 可能会无序传递事件。

  • 如果在跟踪收集期间向后调整用于事件时间戳的时钟，则事件的传递顺序不可预知。 若要避免此问题，请在收集跟踪时 使用 QPC 时钟 而不是系统时钟。
  • 如果在不同的 CPU 上使用相同的时间戳收集多个事件，则事件的传递顺序是不可预知的。
  • 如果事件具有无效的时间戳 (例如由于文件损坏) ，则该事件的传递顺序和跟踪中的其他事件可能是不可预知的。

ProcessTrace 函数会阻止线程，直到它传递所有事件、BufferCallback 函数返回 FALSE 或调用 CloseTrace。 此外，如果使用者实时使用事件，则 ProcessTrace 函数在控制器停止跟踪会话后返回。 (请注意，在函数返回之前可能会有几秒钟的延迟。)

Windows Server 2003： 只能在 ProcessTrace 返回后调用 CloseTrace 。

示例

有关使用 ProcessTrace 的示例，请参阅 使用 TdhFormatProperty 来使用事件数据。

要求

   
最低受支持的客户端 Windows 2000 专业版 [桌面应用 |UWP 应用]
最低受支持的服务器 Windows 2000 Server [桌面应用 |UWP 应用]
目标平台 Windows
标头 evntrace.h
Library Windows 8.1 和 Windows Server 2012 R2 上的 Sechost.lib;Windows 8、Windows Server 2012、Windows 7、Windows Server 2008 R2、Windows Server 2008、Windows Vista 和 Windows XP 上的 Advapi32.lib
DLL Windows 8.1 和 Windows Server 2012 R2 上的 Sechost.dll;Windows 8、Windows Server 2012、Windows 7、Windows Server 2008 R2、Windows Server 2008、Windows Vista 和 Windows XP 上的 Advapi32.dll

请参阅

BufferCallback

EventCallback

EventRecordCallback

OpenTrace