RegisterTraceGuidsA 函数（evntrace.h）

项目
07/16/2024

RegisterTraceGuids 函数注册经典（Windows 2000 样式）ETW 事件跟踪提供程序及其用于生成事件的事件跟踪类。此函数还指定系统用来启用和禁用提供程序跟踪的回调函数。

此函数已过时。新代码应使用 EventRegister 注册 Windows Vista 样式（Crimson） ETW 事件跟踪提供程序。

语法

ULONG WMIAPI RegisterTraceGuidsA(
  [in]      WMIDPREQUEST             RequestAddress,
  [in]      PVOID                    RequestContext,
  [in]      LPCGUID                  ControlGuid,
  [in]      ULONG                    GuidCount,
  [in, out] PTRACE_GUID_REGISTRATION TraceGuidReg,
  [in]      LPCSTR                   MofImagePath,
  [in]      LPCSTR                   MofResourceName,
  [out]     TRACEGUID_HANDLE         *RegistrationHandle
);

参数

[in] RequestAddress

指向 ControlCallback 函数的指针，该函数在事件跟踪会话启用或禁用提供程序时接收通知。 EnableTrace 函数触发此回调。

[in] RequestContext

指向 ETW 传递给 RequestAddress指定的函数的可选提供程序定义的上下文的指针。

[in] ControlGuid

控制注册提供程序的 GUID （提供程序 ID）。

[in] GuidCount

TraceGuidReg 数组中的元素数。如果 TraceGuidRegNULL，请将此参数设置为 0。

[in, out] TraceGuidReg

指向数组的指针
TRACE_GUID_REGISTRATION 结构。

每个元素标识提供程序提供的事件类别。

输入时，每个结构的 Guid 成员包含注册提供程序分配的事件跟踪类 GUID。类 GUID 标识提供程序提供的事件类别。提供程序在调用 traceEvent 函数来记录事件时，使用相同的类 GUID 来设置 EVENT_TRACE_HEADER 的 Guid 成员。

输出时，RegHandle 成员接收事件的类 GUID 注册句柄。如果提供程序调用 TraceEventInstance 函数，请使用 TRACE_GUID_REGISTRATION 的 RegHandle 成员设置 EVENT_INSTANCE_HEADER的 RegHandle 成员。

如果提供程序仅调用 traceEvent 函数来记录事件，则可以 NULL 此参数。如果提供程序调用 TraceEventInstance 函数来记录事件，则此参数不能 NULL。

[in] MofImagePath

不支持此参数。设置为 NULL。在设置应用程序期间，应使用 Mofcomp.exe 注册 MOF 资源。有关详细信息，请参阅发布事件架构。

使用 SP1、Windows XP 和 Windows 2000 Windows XP： 指向可选字符串的指针，该字符串指定包含由 MofResourceName指定的资源的 DLL 或可执行程序的路径。如果事件提供程序和使用者使用另一种机制来共享提供程序使用的事件跟踪类的信息，则可以 NULL。

[in] MofResourceName

不支持此参数。设置为 NULL。在设置应用程序期间，应使用 Mofcomp.exe 注册 MOF 资源。有关详细信息，请参阅发布事件架构。

使用 SP1、Windows XP 和 Windows 2000 Windows XP： 指向可选字符串的指针，该字符串指定 MofImagePath的字符串资源。字符串资源包含二进制 MOF 文件的名称，该文件描述提供程序支持的事件跟踪类。

[out] RegistrationHandle

接收提供程序的注册句柄。调用 UnregisterTraceGuids 函数时，请使用返回的句柄。

重要

DLL 或驱动程序创建的所有注册句柄都必须在 DLL 或驱动程序卸载之前取消注册。如果未注销提供程序，则 ETW 尝试调用提供程序的回调时，将发生崩溃。

返回值

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

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

重要

如果控制器调用 enableTrace 来启用提供程序，并且提供程序尚未 RegisterTraceGuids，则此函数还可以返回 ControlCallback 返回的值。发生这种情况时，RegisterTraceGuids 如果注册成功，将返回回调的返回值。

ERROR_INVALID_PARAMETER

以下情况之一为 true：
- RequestAddressNULL。
- ControlGuidNULL。
- RegistrationHandleNULL。
Windows XP 和 Windows 2000：TraceGuidRegNULL 或 GuidCount 小于或等于零。

言论

注意

大多数开发人员不会直接调用此函数。相反，开发人员通常会使用 ETW 框架。例如，基于 TMF 的 WPP 管理对 RegisterTraceGuids、TraceMessage的调用，并代表你 UnregisterTraceGuids。

此函数将打开经典（Windows 2000 样式）事件提供程序句柄，该句柄可用于通过 TraceEvent、TraceEventInstance、TraceMessage和 TraceMessageVa编写基于 MOF 和 TMF 的 WPP ETW 事件。

注意

若要打开 Windows Vista 样式的提供程序句柄，该句柄通过 EventWrite编写基于清单或 TraceLogging 的 ETW 事件，请使用 EventRegister。

如果提供程序的 ControlGuid 以前已注册并启用，则会自动启用引用同一 ControlGuid 的后续注册。

一个进程最多可以注册 1,024 个提供程序 GUID;但是，应将进程注册的提供程序数限制为一两个。此限制包括使用此函数注册的函数和 EventRegister 函数。

在 Windows Vista 之前：进程可以注册的提供程序数没有限制。

例子

有关使用 RegisterTraceGuids的示例，请参阅编写经典事件。

注意

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

要求

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

另请参阅

EnableTrace

UnregisterTraceGuids

通过

RegisterTraceGuidsA 函数（evntrace.h）

语法

参数

返回值

言论

例子

要求

另请参阅

反馈

其他资源

通过

RegisterTraceGuidsA 函数 （evntrace.h）

语法

参数

返回值

言论

例子

要求

另请参阅

反馈

其他资源

RegisterTraceGuidsA 函数（evntrace.h）