ZwNotifyChangeKey 函数 (ntifs.h)

  • 项目

ZwNotifyChangeKey 例程允许驱动程序在注册表项更改时请求通知。

语法

NTSYSAPI NTSTATUS ZwNotifyChangeKey(
  [in]            HANDLE           KeyHandle,
  [in, optional]  HANDLE           Event,
  [in, optional]  PIO_APC_ROUTINE  ApcRoutine,
  [in, optional]  PVOID            ApcContext,
  [out]           PIO_STATUS_BLOCK IoStatusBlock,
  [in]            ULONG            CompletionFilter,
  [in]            BOOLEAN          WatchTree,
  [out, optional] PVOID            Buffer,
  [in]            ULONG            BufferSize,
  [in]            BOOLEAN          Asynchronous
);

参数

[in] KeyHandle

要为其注册通知例程的密钥的句柄。 此句柄是通过成功调用 ZwCreateKey 或 ZwOpenKey 创建的。 调用方必须指定KEY_NOTIFY访问权限。

[in, optional] Event

调用方创建的事件的可选句柄，在操作完成时要设置为“已信号”状态。 如果不是 NULL，则调用方将置于等待状态，直到操作成功，此时事件设置为“已发出信号”状态。

[in, optional] ApcRoutine

指向调用方提供的 APC 例程的指针，该例程在操作完成后运行。 此参数是可选的，可以为 NULL。

[in, optional] ApcContext

用于作为参数传递给 ApcRoutine 指向的 APC 例程的指针。 如果 ApcRoutine 不是 NULL，并且必须强制转换为 PVOID 类型，则此参数是必需的。 否则，如果 ApcRoutine 为 NULL，则此参数也设置为 NULL。

此参数的含义取决于例程是从内核模式还是从用户模式调用：

  • 对于内核模式调用，请将此参数设置为以下 WORK_QUEUE_TYPE 枚举值之一：

    • CriticalWorkQueue
    • DelayedWorkQueue

  • 对于用户模式调用，此参数指向 APC 例程的调用方指定的上下文。

[out] IoStatusBlock

指向包含最终状态和操作相关信息 的IO_STATUS_BLOCK 结构的指针。 对于返回数据的成功调用，IoStatusBlock-Information> 中提供了写入缓冲区的字节数。

[in] CompletionFilter

导致驱动程序收到通知的操作的位掩码。 指定以下一个或多个标志：

值 含义
REG_NOTIFY_CHANGE_NAME 通知调用方是添加还是删除了子项。
REG_NOTIFY_CHANGE_ATTRIBUTES 向调用方通知项属性（例如安全描述符信息）的更改。
REG_NOTIFY_CHANGE_LAST_SET 向调用方通知项值的更改。 这包括添加或删除值，或更改现有值。 (如果写入密钥的新值与 key 的上一个值匹配，则调用方不会收到通知。)
REG_NOTIFY_CHANGE_SECURITY 向调用方通知项的安全描述符的更改。

[in] WatchTree

如果为 TRUE，则会通知驱动程序指定键的所有子项发生更改。 如果为 FALSE，则仅通知驱动程序对指定密钥的更改。

[out, optional] Buffer

保留。 指定 NULL。

[in] BufferSize

保留。 指定零。

[in] Asynchronous

如果为 FALSE，则在发生指定事件之前，例程不会返回。 如果为 TRUE，则例程将立即返回。

返回值

ZwNotifyChangeKey 例程在成功时返回STATUS_SUCCESS，否则返回相应的 NTSTATUS 值。 如果调用方为 异步 参数指定 TRUE，并且事件尚未发生，则例程将返回STATUS_PENDING。

注解

如果在用户模式下调用 ZwNotifyChangeKey 函数，则应使用名称“NtNotifyChangeKey”而不是“ZwNotifyChangeKey”。

对于来自内核模式驱动程序的调用，Windows 本机系统服务例程的 NtXxx 和 ZwXxx 版本在处理和解释输入参数的方式上的行为可能有所不同。 有关例程的 NtXxx 和 ZwXxx 版本之间的关系的详细信息，请参阅 使用本机系统服务例程的 Nt 和 Zw 版本。

要求

要求 值
最低受支持的客户端 Windows 2000
目标平台 通用
标头 ntifs.h (包括 Ntifs.h)
Library NtosKrnl.lib
DLL NtosKrnl.exe
IRQL PASSIVE_LEVEL
DDI 符合性规则 HwStorPortProhibitedDDI (storport) 、 PowerIrpDDis (wdm)

另请参阅

IO_STATUS_BLOCK

WORK_QUEUE_ITEM

WORK_QUEUE_TYPE

ZwCreateKey

ZwOpenKey