WdfRequestProbeAndLockUserBufferForWrite 函数 (wdfrequest.h)

  • 项目

[仅适用于 KMDF]

WdfRequestProbeAndLockUserBufferForWrite 方法验证 I/O 请求的用户模式缓冲区是否可写，然后锁定缓冲区的物理内存页，以便驱动程序堆栈中的驱动程序可以写入缓冲区。

语法

NTSTATUS WdfRequestProbeAndLockUserBufferForWrite(
  [in]  WDFREQUEST Request,
  [in]  PVOID      Buffer,
  [in]  size_t     Length,
  [out] WDFMEMORY  *MemoryObject
);

参数

[in] Request

框架请求对象的句柄。

[in] Buffer

指向请求输出缓冲区的指针。 有关更多信息，请参见下面的“备注”部分。

[in] Length

请求的输出缓冲区的长度（以字节为单位）。

[out] MemoryObject

指向位置的指针，该位置接收表示用户输出缓冲区的框架内存对象的句柄。

返回值

如果操作成功，WdfRequestProbeAndLockUserBufferForWrite 将返回STATUS_SUCCESS。 否则，此方法可能会返回以下值之一：

返回代码 说明
STATUS_INVALID_PARAMETER
 输入参数无效。
STATUS_INVALID_USER_BUFFER
 Length 参数为零。
STATUS_INVALID_DEVICE_REQUEST
 请求已完成或无效。
STATUS_ACCESS_VIOLATION
 当前线程不是 I/O 请求的创建者。
STATUS_INSUFFICIENT_RESOURCES
 内存不足，无法完成操作。
 

此方法还可能返回其他 NTSTATUS 值。

如果驱动程序提供无效的对象句柄，则会发生 bug 检查。

注解

用户输出缓冲区通常接收驱动程序已从设备读取的信息。

只有顶级驱动程序才能调用 WdfRequestProbeAndLockUserBufferForWrite 方法，因为该方法需要创建 I/O 请求的进程的进程上下文。

Buffer 参数指定的用户模式缓冲区可以是 WdfRequestRetrieveUnsafeUserOutputBuffer 检索的缓冲区，也可以是不同的用户模式输出缓冲区。 例如，使用缓冲访问方法的 I/O 控制代码可能会传递一个结构，该结构包含指向用户模式缓冲区的嵌入指针。 在这种情况下，驱动程序可以使用WdfRequestProbeAndLockUserBufferForWrite 获取缓冲区的内存对象。

Length 参数指定的缓冲区长度不得大于缓冲区的实际大小。 否则，驱动程序可以访问缓冲区外部的内存，这是一种安全风险。

如果 WdfRequestProbeAndLockUserBufferForWrite 返回STATUS_SUCCESS，驱动程序将收到表示用户模式缓冲区的框架内存对象的句柄。 若要访问缓冲区，驱动程序必须调用 WdfMemoryGetBuffer。

驱动程序调用 WdfRequestComplete 时，会自动释放框架内存对象。

有关 WdfRequestProbeAndLockUserBufferForWrite 的详细信息，请参阅 访问 Framework-Based 驱动程序中的数据缓冲区。

示例

有关使用 WdfRequestProbeAndLockUserBufferForWrite 的代码示例，请参阅 WdfRequestProbeAndLockUserBufferForRead。

要求

要求 值
目标平台 通用
最低 KMDF 版本 1.0
标头 wdfrequest.h (包括 Wdf.h)
Library Wdf01000.sys (请参阅框架库版本控制.)
IRQL PASSIVE_LEVEL
DDI 符合性规则 DriverCreate (kmdf) 、 InvalidReqAccess (kmdf) 、 InvalidReqAccessLocal (kmdf) 、 KmdfIrql (kmdf) 、 KmdfIrql2 (kmdf) 、 KmdfIrqlExplicit (kmdf)

另请参阅

WdfMemoryGetBuffer

WdfRequestProbeAndLockUserBufferForRead

WdfRequestRetrieveUnsafeUserOutputBuffer