enableTrace 函数 (evntrace.h)
跟踪会话控制器调用 EnableTrace 来配置 ETW 事件提供程序将事件记录到跟踪会话的方式。
此函数已过时。 EnableTraceEx2 函数取代此函数。
语法
ULONG WMIAPI EnableTrace(
[in] ULONG Enable,
[in] ULONG EnableFlag,
[in] ULONG EnableLevel,
[in] LPCGUID ControlGuid,
CONTROLTRACE_ID TraceId
);
参数
[in] Enable
设置为 1 以启用从提供程序接收事件或调整从提供程序接收事件时使用的设置， (例如更改级别和关键字) 。 设置为 0 可禁用从提供程序接收事件。
[in] EnableFlag
关键字的 32 位位掩码，用于确定你希望提供程序写入的事件类别。 除了满足 EnableLevel critera 之外，如果事件的关键字位与此值中设置的任何位匹配，或者事件没有设置关键字位，则提供程序通常会写入事件。
注意
基于 EventRegister 的提供程序支持 64 位关键字。 使用 EnableTraceEx2 启用使用 64 位 MatchAnyKeyword 掩码 的提供程序。
[in] EnableLevel
一个 值，该值指示你希望提供程序写入的事件的最大级别。 除了满足 EnableFlag 条件外，如果事件的级别小于或等于此值，提供程序通常会写入事件。
此值应介于 1 到 255 的范围内。 Microsoft 定义级别 1-5 的语义，如下所示。 值越小，表示事件越严重。 EnableLevel 的每个值启用指定的级别和所有更严重的级别。 例如，如果指定 TRACE_LEVEL_WARNING，则使用者将收到警告、错误和关键事件。
| 值 | 含义 |
|---|---|
| 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) 。
TraceId
返回值
如果函数成功，则返回值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 |