RegisterTraceGuidsA 函数 (evntrace.h)

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]     PTRACEHANDLE             RegistrationHandle
);

参数

[in] RequestAddress

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

[in] RequestContext

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

[in] ControlGuid

控制注册提供程序 (提供程序 ID) 的 GUID。

[in] GuidCount

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

[in, out] TraceGuidReg

Pointer to an array of
TRACE_GUID_REGISTRATION 结构。

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

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

在输出中, RegHandle 成员接收事件的类 GUID 注册句柄。 如果提供程序调用 TraceEventInstance 函数,请使用 TRACE_GUID_REGISTRATIONRegHandle 成员设置 EVENT_INSTANCE_HEADERRegHandle 成员。

如果提供程序仅调用 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

    下列情况之一存在:

    • RequestAddressNULL
    • ControlGuidNULL
    • RegistrationHandleNULL

    Windows XP 和 Windows 2000:TraceGuidRegNULLGuidCount 小于或等于零。

注解

注意

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

此函数打开经典 (Windows 2000 样式) 事件提供程序句柄,该句柄可用于通过 TraceEvent、TraceEventInstanceTraceMessage 和 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 专业版 [桌面应用|UWP 应用]
最低受支持的服务器 Windows 2000 Server [桌面应用|UWP 应用]
目标平台 Windows
标头 evntrace.h
Library 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