enableTrace 函数 (evntrace.h)

  • 项目

跟踪会话控制器调用 EnableTrace 来配置 ETW 事件提供程序将事件记录到跟踪会话的方式。

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

语法

ULONG WMIAPI EnableTrace(
  [in] ULONG       Enable,
  [in] ULONG       EnableFlag,
  [in] ULONG       EnableLevel,
  [in] LPCGUID     ControlGuid,
  [in] TRACEHANDLE TraceHandle
);

参数

[in] Enable

设置为 1 以启用从提供程序接收事件或调整从提供程序接收事件时使用的设置， (例如更改级别和关键字) 。 设置为 0 可禁用从提供程序接收事件。

[in] EnableFlag

关键字的 32 位位掩码，用于确定你希望提供程序写入的事件类别。 如果事件的关键字 (keyword) 位与此值中设置的任何位匹配，或者事件除了满足 EnableLevel critera 之外没有设置关键字 (keyword) 位，则提供程序通常会写入事件。

注意

基于 EventRegister 的提供程序支持 64 位关键字。 使用 EnableTraceEx2 启用使用 64 位 MatchAnyKeyword 掩码 的提供程序。

[in] EnableLevel

一个 值，该值指示你希望提供程序写入的事件的最大级别。 除了满足 EnableFlag 条件外，如果事件的级别小于或等于此值，提供程序通常会写入事件。

此值应介于 1 到 255 的范围内。 Microsoft 定义级别 1-5 的语义，如下所示。 值越小，表示事件越严重。 EnableLevel 的每个值启用指定的级别和所有更严重的级别。 例如，如果指定 TRACE_LEVEL_WARNING，则使用者将收到警告、错误和关键事件。

Value 含义
TRACE_LEVEL_CRITICAL (1) 异常退出或终止事件
TRACE_LEVEL_ERROR (2) 严重错误事件
TRACE_LEVEL_WARNING (3) 警告事件，例如分配失败
TRACE_LEVEL_INFORMATION (4) 非错误信息事件
TRACE_LEVEL_VERBOSE (5) 详细诊断事件

常 TRACE_LEVEL 量在 evntrace.h 中定义。 等效 WINMETA_LEVEL 常量在 winmeta.h 中定义。

[in] ControlGuid

控件 GUID (要启用或禁用的事件提供程序的提供程序 ID) 。

[in] TraceHandle

要为其配置提供程序的事件跟踪会话的句柄。 启动新的跟踪时 ，StartTrace 函数返回此句柄。 若要获取现有跟踪的句柄，请使用 ControlTrace 根据跟踪的名称查询跟踪属性，然后从返回EVENT_TRACE_PROPERTIES数据的 Wnode.HistoricalContext 字段中获取句柄。

返回值

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

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

  • ERROR_INVALID_PARAMETER

    下列情况之一存在：

    • ControlGuid 为 NULL。
    • TraceHandle 为 NULL。

  • ERROR_INVALID_FUNCTION

    未注册提供程序时，无法更改启用标志和级别。

  • ERROR_WMI_GUID_NOT_FOUND

    提供程序未注册。 安装 KB307331 或 Windows 2000 Service Pack 4 且未注册提供程序时发生。 若要避免此错误，必须先注册提供程序。

  • ERROR_NO_SYSTEM_RESOURCES

    超出了可以启用提供程序的跟踪会话数。

  • ERROR_ACCESS_DENIED

    只有具有管理权限的用户、组中的用户Performance Log Users以及以 、 LocalService或 NetworkService 身份LocalSystem运行的服务才能启用跨进程会话的事件提供程序。 若要授予受限用户启用事件提供程序的能力，请将他们添加到 Performance Log Users 组或参阅 EventAccessControl。

    Windows XP 和 Windows 2000： 任何人都可以启用事件提供程序。

备注

事件跟踪控制器调用此函数以配置将事件写入会话的事件提供程序。 例如，控制器可能调用此函数以开始从提供程序收集事件、调整从提供程序收集的事件的级别或关键字，或停止从提供程序收集事件。

此函数已过时。 对于其他功能，新代码应使用 EnableTraceEx2。

以下两个函数调用是等效的：

// Obsolete:
Status = EnableTrace(
    Enable,
    EnableFlag,
    EnableLevel,
    ControlGuid,
    TraceHandle);

// Updated equivalent code:
Status = EnableTraceEx2(
    TraceHandle,
    ControlGuid,
    Enable,      // ControlCode
    EnableLevel,
    EnableFlag,  // MatchAnyKeyword
    0,           // MatchAllKeyword
    0,           // Timeout
    NULL);       // EnableParameters

有关为会话配置提供程序的语义的其他详细信息，请参阅 EnableTraceEx2 的文档。

要求

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

请参阅

StartTrace

EnableTraceEx2