TraceLoggingRegister 函数 (traceloggingprovider.h)

注册 TraceLogging 提供程序,以便可用于记录事件。 注册有效,直到取消注册提供程序或进程退出。

语法

TLG_STATUS TraceLoggingRegister(
  TraceLoggingHProvider hProvider
);

参数

hProvider

要注册的 TraceLogging 提供程序的句柄。 该句柄必须尚未注册。

返回值

如果从用户模式代码调用此函数,该函数将返回一个 HRESULTSUCCEEDED()使用宏确定函数是否成功。

如果从内核模式代码调用此函数,该函数将返回一个 NTSTATUSNT_SUCCESS()使用宏确定函数是否成功。

注意

TraceLoggingRegister 返回的错误代码主要用于调试和诊断方案。 即使 ETW 提供程序注册失败,大多数生产代码仍应继续运行,因此发布版本通常应忽略 TraceLoggingRegister 返回的错误代码。

注解

当组件开始运行时,组件中的任何 TraceLogging 提供程序句柄都将处于未注册状态,并且任何使用提供程序的句柄生成事件的尝试都将被无提示地忽略。 在提供程序可以写入任何事件之前,需要使用 TraceLoggingRegister 注册提供程序。 通常在组件启动期间执行此操作,例如,在main、、wmainWinMain、或DllMain(DLL_PROCESS_ATTACH)DriverEntry。 在组件关闭时,通过调用 TraceLoggingUnregister 注销提供程序。

不要在已注册的提供程序句柄上调用 TraceLoggingRegister 。 可以取消注册句柄,然后在必要时再次注册它,尽管反复注册和注销句柄可能会导致性能问题,但应避免 (,即不要注册、写入几个事件,然后注销;而是在组件启动时注册一次,并在组件关闭时注销) 。

对于同一句柄上对 TraceLoggingRegister 或 TraceLoggingUnregister 的其他调用,TraceLoggingRegister 不是线程安全的。 如果另一个线程可能同时在同一句柄上调用 TraceLoggingRegister 或 TraceLoggingUnregister,请不要调用 TraceLoggingRegister

如果 TraceLoggingRegister 失败,提供程序句柄将保持未注册状态,并且提供程序句柄的所有使用都将安全无操作。 具体而言,使用未注册的提供程序句柄调用 TraceLoggingWriteTraceLoggingUnregister 是一种安全的无操作操作。

重要

如果 DLL 或驱动程序在提供程序句柄上调用 TraceLoggingRegister ,则在 DLL 或驱动程序卸载之前,它 必须在 该提供程序句柄上调用 TraceLoggingUnregister 。 如果 DLL 卸载而不调用 TraceLoggingUnregister,则该过程随后可能会崩溃。 如果驱动程序在未调用 TraceLoggingUnregister 的情况下卸载,系统随后可能会崩溃。 TraceLoggingRegister 函数建立 ETW 配置回调,TraceLoggingUnregister 取消回调。 如果未取消回调并且模块卸载,则下次 ETW 尝试调用回调时将发生崩溃。

警告

如果驱动程序调用 TraceLoggingRegister,然后在 DriverEntry 期间遇到错误,则在从 DriverEntry 返回错误之前,它必须调用 TraceLoggingUnregister。 如果驱动程序从 DriverEntry 返回错误,并且调用 TraceLoggingUnregister 会导致系统崩溃,则不会调用正常的驱动程序清理例程。

TraceLoggingRegister 执行以下操作:

TraceLoggingRegister 的调用与对具有 NULL 的回调上下文参数的 TraceLoggingRegisterEx 的调用相同。 如果需要在会话启用或禁用提供程序时收到 ETW 启用回调,请使用 TraceLoggingRegisterEx

要求

   
最低受支持的客户端 Windows Vista [桌面应用|UWP 应用]
最低受支持的服务器 Windows Server 2008 [桌面应用|UWP 应用]
标头 traceloggingprovider.h
Library Advapi32.lib

另请参阅

EventRegister

TraceLoggingRegisterEx

TraceLoggingUnregister

TraceLoggingWrite

TRACELOGGING_DEFINE_PROVIDER