Share via

etwRegister 函数 (wdm.h)

  • 项目

EtwRegister 函数注册事件提供程序，并且必须先调用该提供程序，然后提供程序才能开始跟踪。 EtwRegister 函数是用户模式 EventRegister 函数的内核模式对应函数。 函数还可以提供指向可选回调函数的指针，该函数可用于提供其他事件筛选功能。

语法

NTSTATUS EtwRegister(
  [in]           LPCGUID            ProviderId,
  [in, optional] PETWENABLECALLBACK EnableCallback,
  [in, optional] PVOID              CallbackContext,
  [out]          PREGHANDLE         RegHandle
);

参数

[in] ProviderId

指向事件提供程序 GUID 的指针。

[in, optional] EnableCallback

指向可选回调函数的指针。 回调函数提供其他事件筛选功能。 回调函数是用户定义的。

[in, optional] CallbackContext

执行回调时，函数会传回可选的回调上下文。 注册提供程序时，可以指定可选上下文。 CallbackContext 参数支持多个提供程序共享一个回调的方案，如在 C++ 类中一样。 CallbackContext 提供了一种区分启用回调的目标提供程序实例的方法。

[out] RegHandle

指向变量的指针，该变量在函数调用成功时接收提供程序注册句柄。

返回值

EtwRegister 函数从以下列表中返回状态代码：

返回代码 说明
STATUS_SUCCESS
指示事件提供程序已成功注册到 ETW。
STATUS_INVALID_PARAMETER
指示参数无效。
STATUS_Xxx
指示请求因 NTSTATUS 值指定的原因而失败。 有关实际状态返回代码的详细信息，请参阅 Ntstatus.h。

注解

在内核模式驱动程序可以跟踪事件之前，驱动程序必须使用 EtwRegister 函数注册为事件提供程序。 当内核模式驱动程序调用 EtwRegister 时，函数将返回注册句柄。 此注册句柄可用于测试是否为特定提供程序启用了关键字 (keyword) 或级别，以及调用事件跟踪和日志记录函数。 跟踪完成后，驱动程序必须调用 EtwUnregister 函数才能注销提供程序。 每次调用 EtwRegister 时，都必须有对 EtwUnregister 的相应调用。 未能注销事件提供程序可能会导致卸载进程时出错，因为与进程关联的回调函数不再有效。 不应在 EtwRegister 和 EtwUnregister 函数绑定的代码之外进行跟踪调用。 为了获得最佳性能，可以在 DriverEntry 例程中调用 EtwRegister 函数，在 DriverUnload 例程中调用 EtwUnregister 函数。

EtwRegister 的调用方必须在系统线程上下文中的 IRQL = PASSIVE_LEVEL 运行。

要求

要求 值
最低受支持的客户端 在 Windows Vista 和更高版本的 Windows 中可用。
目标平台 通用
标头 wdm.h (包括 Wdm.h、Ntddk.h)
Library NtosKrnl.lib
DLL NtosKrnl.exe
IRQL PASSIVE_LEVEL
DDI 符合性规则 HwStorPortProhibitedDDI (storport) ， PowerIrpDDis (wdm)

另请参阅

EtwUnregister