Share via

openTraceA 函数 (evntrace.h)

  • 项目

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

    如果未指定 EVENT_TRACE_LOGFILE 的 LoggerName 成员，则必须指定有效的日志文件名。

  • ERROR_ACCESS_DENIED

    只有具有管理权限的用户、性能日志用户组的用户以及作为 LocalSystem、LocalService、NetworkService 运行的服务才能实时使用事件。 若要授予受限用户实时使用事件的能力，请将其添加到“性能日志用户”组。

    Windows XP 和 Windows 2000： 任何人都可以使用实时事件。

注解

跟踪使用者调用此函数以打开跟踪处理会话。

调用 OpenTrace 后，调用 ProcessTrace 函数来处理事件。 处理完事件后，调用 CloseTrace 函数以关闭跟踪处理句柄。

示例

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

注意

evntrace.h 标头将 OpenTrace 定义为别名，该别名根据 UNICODE 预处理器常量的定义自动选择此函数的 ANSI 或 Unicode 版本。 将非特定编码别名与非非特定编码的代码混合使用可能会导致不匹配，从而导致编译或运行时错误。 有关详细信息，请参阅 函数原型的约定。

要求

要求 值
最低受支持的客户端 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

另请参阅

CloseTrace

EVENT_TRACE_LOGFILE

ProcessTrace