TraceLoggingRegister 函数 (traceloggingprovider.h)

  • 项目

注册 TraceLogging 提供程序，以便可用于记录事件。 注册在取消注册提供程序或进程退出之前有效。

语法

TLG_STATUS TraceLoggingRegister(
  TraceLoggingHProvider hProvider
);

参数

hProvider

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

返回值

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

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

注意

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

注解

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

不要在已注册的提供程序句柄上调用 TraceLoggingRegister 。 可以注销句柄，然后在必要时再次注册，但重复注册和注销句柄可能会导致性能问题，应避免 (即不注册、写入一些事件，然后注销;相反，请在组件启动时注册一次，并在组件关闭) 注销。

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

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

重要

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

警告

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

TraceLoggingRegister 执行以下操作：

对 TraceLoggingRegister 的调用与调用 TraceLoggingRegisterEx （针对 回调 和 上下文 参数使用 NULL）相同。 如果在会话启用或禁用提供程序时需要接收 ETW 启用回调，请使用 TraceLoggingRegisterEx。

要求

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

另请参阅

EventRegister

TraceLoggingRegisterEx

TraceLoggingUnregister

TraceLoggingWrite

TRACELOGGING_DEFINE_PROVIDER