exRegisterCallback 函数 (wdm.h)

项目
02/29/2024

ExRegisterCallback 例程使用给定的回调对象注册给定的回调例程。

语法

PVOID ExRegisterCallback(
  [in, out]      PCALLBACK_OBJECT   CallbackObject,
  [in]           PCALLBACK_FUNCTION CallbackFunction,
  [in, optional] PVOID              CallbackContext
);

参数

[in, out] CallbackObject

指向从 ExCreateCallback 例程获取的回调对象的指针。

[in] CallbackFunction

指向驱动程序实现的回调例程的指针，该例程必须是不可分页的。回调例程必须符合以下原型：

VOID
(*PCALLBACK_FUNCTION ) (
    IN PVOID CallbackContext,
    IN PVOID Argument1,
    IN PVOID Argument2
    );

回调例程参数如下所示：

CallbackContext

指向驱动程序提供的上下文区域的指针，如 ExRegisterCallback 的 CallbackContext 参数所指定。

Argument1

指向回调对象定义的参数的指针。

Argument2

指向回调对象定义的参数的指针。

[in, optional] CallbackContext

指向每次调用回调例程时要作为回调例程的上下文参数传递的数据项的调用方定义的结构的指针。通常，上下文是调用方设备对象扩展的一部分。

返回值

ExRegisterCallback 返回指向回调注册句柄的指针，该句柄应被视为不透明并保留供系统使用。如果 ExRegisterCallback 完成并出现错误，则此指针为 NULL。

注解

驱动程序调用 ExRegisterCallback 以使用指定的回调对象注册回调例程。

如果对象只允许一个已注册的回调例程，并且此类例程已注册， 则 ExRegisterCallback 将返回 NULL。

ExRegisterCallback 的调用方必须保存返回的指针，以便稍后在调用 ExUnregisterCallback 时使用。从回调对象的已注册回调例程列表中删除回调例程时，需要指针。

已注册回调例程的 Argument1 和 Argument2 的含义取决于回调对象，并由创建它的组件定义。以下是系统定义的回调对象的参数：

\Callback\SetSystemTime

Argument1 (SetSystemTime)

未使用。

Argument2 (SetSystemTime)

未使用。

\Callback\PowerState**

Argument1 (PowerState)

强制转换为 PVOID 类型的PO_CB_XXX常量值。
PO_CB_AC_STATUS — 指示系统已从 A/C 更改为电池电源，反之亦然。
PO_CB_LID_SWITCH_STATE — 指示盖子开关已更改状态。
PO_CB_PROCESSOR_POWER_POLICY — 指示系统处理器电源策略已更改。
PO_CB_SYSTEM_POWER_POLICY — 指示系统电源策略已更改。
PO_CB_SYSTEM_STATE_LOCK — 指示系统电源状态即将发生更改。分页路径中的驱动程序可以注册此回调，以接收此类更改的早期警告，从而有机会在电源状态更改之前将其代码锁定在内存中。

Argument2 (PowerState)

强制转换为 PVOID 类型的 TRUE 或 FALSE 值。

如果 Argument1 PO_CB_AC_STATUS，则如果计算机当前使用 A/C 电源， 则 Argument2 为 TRUE ;如果计算机使用电池电源运行，则为 FALSE 。
如果 Argument1 PO_CB_LID_SWITCH_STATE，则当盖子当前打开时 ，Argument2 为 TRUE ;如果盖子关闭，则为 FALSE 。
如果 argument1 PO_CB_PROCESSOR_POWER_POLICY，则不使用 Argument2 。
如果 argument1 PO_CB_SYSTEM_POWER_POLICY，则不使用 Argument2 。
如果 Argument1 PO_CB_SYSTEM_STATE_LOCK，则 Argument2 在计算机即将退出系统电源状态 S0 时为 FALSE ;如果计算机刚刚重新进入 S0，则为 TRUE 。

\Callback\ProcessorAdd

Argument1 (ProcessorAdd)

指向描述处理器更改通知事件的 KE_PROCESSOR_CHANGE_NOTIFY_CONTEXT 结构的指针。此指针将强制转换为类型 PVOID。回调例程不得修改此结构的内容。

Argument2 (ProcessorAdd)

指向包含 NTSTATUS 值的变量的指针。此指针将强制转换为类型 PVOID。在某些情况下，回调例程可以将错误状态值写入此变量，以指示不应添加新处理器的原因。设备驱动程序不得更改此变量的值，除非满足以下所有三个条件：

处理回调例程期间发生错误，应阻止添加新处理器。
Argument1 指向的 KE_PROCESSOR_CHANGE_NOTIFY_CONTEXT 结构的 State 成员的值为 KeProcessorAddStartNotify。
Argument2 指向的 NSTATUS 变量包含STATUS_SUCCESS值。也就是说，回调例程不得覆盖以前由另一个回调通知客户端写入的错误状态值。

从 Windows Vista 开始， \Callback\ProcessorAdd 回调对象可用于动态跟踪处理器填充中的更改。 KeRegisterProcessorChangeCallback 例程提供类似的信息，但另外还支持KE_PROCESSOR_CHANGE_ADD_EXISTING标志，驱动程序可以使用该标志枚举初始多处理器系统配置中的处理器。对于在 Windows Server 2008 及更高版本的 Windows 中运行的驱动程序，如果可能，请使用 KeRegisterProcessorChangeCallback 而不是 \Callback\ProcessorAdd 回调对象。

有关回调对象的详细信息，请参阅回调对象。

操作系统在创建回调的驱动程序调用 ExNotifyCallback 例程的同一 IRQL 上调用已注册的回调例程。

要求

要求	值
目标平台	通用
标头	wdm.h（包括 Wdm.h、Ntddk.h、Ntifs.h）
Library	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	IRQL <= APC_LEVEL
DDI 符合性规则	HwStorPortProhibitedDDI (storport) ， IrqlExApcLte2 (wdm)