通过

UpdateTraceW 函数 (evntrace.h)

  • 项目

UpdateTrace 函数更新指定事件跟踪会话的属性设置。

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

语法

ULONG WMIAPI UpdateTraceW(
  CONTROLTRACE_ID         TraceId,
  LPCWSTR                 InstanceName,
  PEVENT_TRACE_PROPERTIES Properties
);

参数

TraceId

InstanceName

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

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

Properties

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

在输入时，成员必须为要更新的属性指定新值。 有关可以更新的属性的信息，请参阅备注。

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

返回值

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

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

  • ERROR_BAD_LENGTH

    Properties 的 Wnode 成员的 BufferSize 成员指定了不正确的大小。

  • ERROR_INVALID_PARAMETER

    下列情况之一存在：

    • 属性 为 NULL。
    • InstanceName 和 TraceHandle 均为 NULL。
    • InstanceName 为 NULL，TraceHandle 不是有效的句柄。
    • Properties 的 LogFileNameOffset 成员无效。
    • Properties 的 LoggerNameOffset 成员无效。

    Windows Server 2003 和 Windows XP：Wnode 结构的 Guid 成员是 SystemTraceControlGuid，但 InstanceName 参数不是KERNEL_LOGGER_NAME。

  • ERROR_ACCESS_DENIED

    只有具有管理权限的用户、性能日志用户组中的用户以及作为 LocalSystem、LocalService、NetworkService 运行的服务才能控制事件跟踪会话。 若要授予受限用户控制跟踪会话的能力，请将这些用户添加到“性能日志用户”组。

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

注解

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

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

在输入时，成员必须为要更新的属性指定新值。 可以更新以下属性。

  • EnableFlags：将此成员设置为 0 以禁用所有内核提供程序。 否则，必须指定要启用或保持启用的内核提供程序。 仅适用于系统记录器会话。

  • FlushTimer：如果要更改刷新缓冲区前等待的时间，请设置此成员。 如果此成员为 0，则不会更新该成员。

  • LogFileNameOffset：如果要切换到另一个日志文件，请设置此成员。 如果此成员为 0，则不更新文件名。 如果偏移量不为零，并且不更改日志文件名，则函数将返回错误。

  • LogFileMode：如果要打开和关闭 EVENT_TRACE_REAL_TIME_MODE ，请设置此成员。 若要关闭实时消耗时间，请将此成员设置为 0。 若要打开实时模式，请将此成员设置为 EVENT_TRACE_REAL_TIME_MODE 并且它将与当前模式一起为 OR。

  • MaximumBuffers：如果要更改 ETW 使用的最大缓冲区数，请设置此成员。 如果此成员为 0，则不会更新该成员。

对于专用记录器会话，只能更新 LogFileNameOffset 和 FlushTimer。

如果使用新初始化 EVENT_TRACE_PROPERTIES 结构，则除要更新的成员外，需要指定的唯一成员是 Wnode.BufferSize、 Wnode.Guid 和 Wnode.Flags。

如果使用传递给 StartTrace 的属性结构，请确保 LogFileNameOffset 成员为 0，除非更改日志文件名。

如果调用 ControlTrace 函数来查询当前会话属性，然后更新这些属性以更新会话，请确保将 LogFileNameOffset 设置为 0 (，除非更改日志文件名) 并设置EVENT_TRACE_PROPERTIES。要WNODE_FLAG_TRACED_GUID的 Wnode.Flags。

若要获取事件跟踪会话的属性设置和会话统计信息，请调用 ControlTrace 函数。

示例

有关使用 UpdateTrace 的示例，请参阅 更新事件跟踪会话。

注意

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

要求

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

另请参阅

ControlTrace