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 数组中的元素数。 如果 TraceGuidReg 为 NULL，请将此参数设置为 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

    下列情况之一存在：

    • RequestAddress 为 NULL。
    • ControlGuid 为 NULL。
    • RegistrationHandle 为 NULL。

    Windows XP 和 Windows 2000：TraceGuidReg 为 NULL 或 GuidCount 小于或等于零。

备注

注意

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

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

注意

若要打开通过 EventWrite 写入基于清单或 TraceLogging 的 ETW 事件的 Windows Vista 样式提供程序句柄，请使用 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