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
当跟踪会话启用或禁用此提供程序时,ETW 将调用的可选 EnableCallback 。 如果需要任何回调,请使用 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 |