ProbeForWrite 函数 (wdm.h)

  • 项目

警告

建议不要在当前软件中使用 ProbeForWrite 函数，它仅用于实现历史兼容性。 验证用户缓冲区时，请改用 ProbeForRead 。 有关详细信息，请参阅“备注”。

ProbeForWrite 例程检查用户模式缓冲区是否实际驻留在地址空间的用户模式部分、是否可写以及是否正确对齐。

语法

void ProbeForWrite(
  [in, out] volatile VOID *Address,
  [in]      SIZE_T        Length,
  [in]      ULONG         Alignment
);

参数

[in, out] Address

指定用户模式缓冲区的开头。

[in] Length

指定用户模式缓冲区的长度（以字节为单位）。 请参阅“备注”部分中的其他信息。

[in] Alignment

指定用户模式缓冲区开头的所需对齐方式（以字节为单位）。

返回值

无

备注

此函数通常与 ProbeForRead 没有实质性优势，因为必须始终准备好可靠的驱动程序来处理用户模式虚拟地址空间中的保护更改，包括执行 ProbeForWrite 调用后删除对传递给驱动程序的缓冲区的写入权限的保护更改。 由于 ProbeForWrite 访问提供的缓冲区中的每个页面，因此，由于访问每个页面的开销，性能可能会降低，尤其是在提供的缓冲区描述虚拟地址空间的大区域时。 此外，由于 ProbeForWrite 写入每个页面，因此同一缓冲区可能无法安全地用于多个并发驱动程序请求。 出于这些原因，新的驱动程序代码应始终改用 ProbeForRead 。

下表概述了每个内核模式缓冲区探测例程的属性：

行为 ProbeForRead ProbeForWrite
如果长度不为零，则确认缓冲区描述用户模式地址空间中的区域 x x
确认缓冲区基址和长度不会超过最大指针值 x x
如果长度不为零，则确认缓冲区与请求的对齐边界对齐 x x
确认缓冲区最初是可写的 (如果用户模式应用程序重新保护其地址空间) x
访问缓冲区中的每个页面， (额外的开销) x
如果同一缓冲区与多个驱动程序请求并行使用，则修改缓冲区中的每个页 (可能会导致意外行为) x

过去，在某些不遵循内核模式代码的只读权限的处理器上， ProbeForWrite 和 ProbeForRead 之间存在有意义的功能差异。 在这些情况下，操作系统以前依赖于 ProbeForWrite 执行显式分页可写性检查。 对于 Windows NT 4.0 或更高版本支持的任何处理器，这种区别不再有意义。

旧版备注

内核模式驱动程序可以使用 ProbeForWrite 来验证对用户空间中分配的缓冲区的写入访问权限。 它最常在METHOD_NEITHER I/O 期间用于验证 Irp-UserBuffer> 指向的用户缓冲区。

如果指定的内存范围不是有效的用户模式地址范围或不可写 (无访问权限、只读等) ， 则 ProbeForWrite 将引发STATUS_ACCESS_VIOLATION异常。 如果地址范围的开头在 Alignment 指定的字节边界上不对齐， ProbeForWrite 将引发STATUS_DATATYPE_MISALIGNMENT异常。

驱动程序必须在 try/except 块内调用 ProbeForWrite。 如果例程引发异常，驱动程序应使用相应的错误完成 IRP。 请注意，驱动程序对用户模式缓冲区的后续访问也必须封装在 try/except 块中：恶意应用程序可能随时有另一个线程删除、替换或更改用户地址范围的保护， (即使在调用 ProbeForRead 或 ProbeForWrite) 之后或期间也是如此。 有关详细信息，请参阅 处理异常。

请勿在内核模式地址上使用此例程;它将引发异常。

如果 Irp-RequestorMode> = KernelMode，则 Irp-AssociatedIrp.SystemBuffer> 和 Irp-UserBuffer> 字段不包含用户模式地址，并且调用 ProbeForWrite 以探测任一字段指向的缓冲区将引发异常。

如果 Length = 0， 则 ProbeForWrite 不检查地址。 在这种情况下，例程不会对未对齐或超出有效用户地址范围的地址引发异常。

要求

要求 值
最低受支持的客户端 从 Windows 2000 开始可用。
目标平台 通用
标头 wdm.h（包括 Wdm.h、Ntddk.h、Ntifs.h）
Library NtosKrnl.lib
DLL NtosKrnl.exe
IRQL <= APC_LEVEL
DDI 符合性规则 HwStorPortProhibitedDDI (storport) ， IrqlExApcLte2 (wdm)

另请参阅

ProbeForRead