EventRegister 函数 (evntprov.h)

  • 项目

注册 ETW 事件提供程序，创建可用于编写 ETW 事件的句柄。

语法

ULONG EVNTAPI EventRegister(
  [in]           LPCGUID         ProviderId,
  [in, optional] PENABLECALLBACK EnableCallback,
  [in, optional] PVOID           CallbackContext,
  [out]          PREGHANDLE      RegHandle
);

参数

[in] ProviderId

唯一标识提供程序的 GUID，有时称为控件 GUID。 这必须是一个稳定的标识符，以便跟踪控制器可以使用 GUID 订阅来自此提供程序的事件。

[in, optional] EnableCallback

可选 EnableCallback ，ETW 将在跟踪会话启用或禁用此提供程序时调用。 如果不需要回调，请使用 NULL 。

[in, optional] CallbackContext

调用 EnableCallback 时，ETW 将提供的可选上下文数据。 如果不需要回调上下文，请使用 NULL 。

[out] RegHandle

接收事件提供程序注册句柄。 句柄用于对提供程序 API 的后续调用，例如 EventWrite、 EventProviderEnabled 和 EventRegister。

在提供程序卸载或退出之前，请通过调用 EventUnregister 释放提供程序注册句柄。 在不释放其注册的所有提供程序句柄的情况下卸载的 DLL 可能会导致进程崩溃。

返回值

如果成功，则返回 ERROR_SUCCESS 。

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

备注

EventRegister 创建一个句柄，可用于通过 EventWrite、 EventWriteTransfer 或 EventWriteEx 编写 ETW 事件。

注意

大多数事件提供程序不会直接调用 EventRegister 。 相反，大多数事件提供程序是使用 ETW 框架实现的，该框架包装对 EventRegister、 EventWrite 和 EventUnregister 的调用。 例如，可以 编写事件清单 ，然后使用 消息编译器 为事件生成 C/C++ 代码，也可以使用 TraceLogging 来避免需要清单。

不应将事件提供程序的注册与事件提供程序清单的安装混淆。

  • EventRegister API 执行事件提供程序的注册以创建提供程序句柄。 这是一个进程范围操作， (句柄仅在进程) 内有效。 句柄可用于编写 ETW 事件。 使用 句柄写入的所有事件都将使用提供程序注册期间指定的 ProviderId 进行标记。 无需安装清单来编写事件或捕获跟踪 (但可能需要安装清单来解码提供程序的事件或提供程序使用事件日志) 。
  • wevtutil.exe 工具用于安装或卸载事件提供程序的清单。 事件提供程序清单的安装意味着清单中的信息将记录在系统上。 记录的信息是系统全局的，一直保留到卸载清单为止。 记录的信息包括清单中定义的提供程序的名称、GUID、通道和资源 DLL 路径。 清单中的信息由跟踪解码工具和事件日志使用。

大多数组件将在组件初始化时注册其事件提供程序，并在组件关闭时注销其事件提供程序。 例如，应用程序 (EXE) 可能会在应用程序启动期间注册，并在应用程序退出期间注销。 动态库 (DLL) 可能会在进程附加期间注册， DllMain 也可能在进程分离期间注销 DllMain 。

由于事件跟踪是调试/诊断问题，并且通常不是应用程序关键功能，因此大多数零售应用程序应以无提示方式忽略 EventRegister 返回的故障。 如果失败， EventRegister 会将 RegHandle 参数设置为零，以便后续使用 RegHandle (，即在调用 EventWrite 和 EventUnregister 时) 将不起作用。

每个进程最多可以注册 1，024 个提供程序。 但是，应将组件注册的提供程序数限制为一个或两个。 此限制包括使用此函数注册的提供程序和使用 RegisterTraceGuids 注册的提供程序。

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

要求

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

请参阅

EnableCallback

EventWrite

EventUnregister