StopTraceA 函数 (evntrace.h)

  • 项目

StopTrace 函数停止指定的事件跟踪会话。

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

语法

ULONG WMIAPI StopTraceA(
  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 结构的指针。

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

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

返回值

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

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

  • ERROR_BAD_LENGTH

    下列情况之一存在：

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

  • ERROR_INVALID_PARAMETER

    下列情况之一存在：

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

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

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

注解

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

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

如果 LogFileMode 包含EVENT_TRACE_FILE_MODE_PREALLOCATE，StartTrace 会将日志文件扩展到 MaximumFileSize 字节。 文件在日志记录期间占用整个空间，用于循环日志和顺序日志。 停止记录器时，日志文件将减小到所需的大小。

不要从 Dll 调用 StopTraceMain (可能会导致死锁) 。

注意

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

要求

要求 值
最低受支持的客户端 Windows 2000 专业版 [桌面应用 |UWP 应用]
最低受支持的服务器 Windows 2000 Server [桌面应用 |UWP 应用]
目标平台 Windows
标头 evntrace.h
Library Windows 8.1 上的 Sechost.lib 和 Windows Server 2012 R2;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

另请参阅

ControlTrace

StartTrace