queryTraceA 函数 (evntrace.h)

QueryTrace 函数检索指定事件跟踪会话的属性设置和会话统计信息。

此函数已过时。 ControlTrace 函数取代此函数。

语法

ULONG WMIAPI QueryTraceA(
  TRACEHANDLE             TraceHandle,
  LPCSTR                  InstanceName,
  PEVENT_TRACE_PROPERTIES Properties
);

参数

TraceHandle

要查询的事件跟踪会话的句柄，或 0。 如果 InstanceName 为 NULL，则必须指定非零 TraceHandle。 仅当 InstanceName 为 NULL 时，才会使用此参数。 该句柄由 StartTrace 返回。

InstanceName

要查询的事件跟踪会话的名称，或 NULL。 如果 TraceHandle 为 0，则必须指定 InstanceName。

若要指定 NT 内核记录器会话，请将 InstanceName 设置为 KERNEL_LOGGER_NAME。

Properties

指向已初始化 EVENT_TRACE_PROPERTIES 结构的指针。

只需设置 EVENT_TRACE_PROPERTIES 结构的 Wnode.BufferSize 成员。 可以使用最大会话名称 (1024 个字符) 和最大日志文件名 (1024 个字符) 长度来计算缓冲区大小和偏移量（如果未知）。

在输出中，结构成员包含事件跟踪会话的属性设置和会话统计信息。

从 Windows 10 版本 1703 开始：为了在跨进程方案中获得更好的性能，现在可以将筛选传递到 QueryTrace 中，以用于系统范围的专用记录器。 需要传入新的 EVENT_TRACE_PROPERTIES_V2 结构，以包含筛选信息。 有关更多详细信息，请参阅 配置和启动专用记录器会话 。

返回值

如果函数成功，则返回值为 ERROR_SUCCESS。

如果函数失败，则返回值为 系统错误代码之一。 下面是一些常见错误及其原因。

• ERROR_BAD_LENGTH

  下列情况之一存在：

  • Properties 的 Wnode.BufferSize 成员指定的大小不正确。
  • 如果) 使用，则属性没有足够的空间来保存会话名称和日志文件名的副本 (。

• ERROR_INVALID_PARAMETER

  下列情况之一存在：

  • 属性 为 NULL。
  • InstanceName 和 TraceHandle 均为 NULL。
  • InstanceName 为 NULL，TraceHandle 不是有效的句柄。

• ERROR_ACCESS_DENIED

  只有使用提升的管理权限运行的用户、性能日志用户组中的用户以及作为 LocalSystem、LocalService、NetworkService 运行的服务才能查询事件跟踪会话。 若要授予受限用户查询跟踪会话的权限，请将其添加到“性能日志用户”组或查看 EventAccessControl。

  Windows XP 和 Windows 2000： 任何人都可以控制跟踪会话。

• ERROR_WMI_INSTANCE_NOT_FOUND

  给定的会话未运行。

注解

事件跟踪控制器调用此函数。

此函数已过时。 请改用 ControlTrace ，将 ControlCode 设置为 EVENT_TRACE_CONTROL_QUERY。

注意

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

要求

要求	值
最低受支持的客户端	Windows 2000 专业版 [桌面应用 |UWP 应用]
最低受支持的服务器	Windows 2000 Server [桌面应用 |UWP 应用]
目标平台	Windows
标头	evntrace.h
Library	Advapi32.lib
DLL	Advapi32.dll

另请参阅

ControlTrace

QueryAllTraces