WdfRequestRetrieveOutputBuffer 函数 （wdfrequest.h）
[适用于 KMDF 和 UMDF]
WdfRequestRetrieveOutputBuffer 方法检索 I/O 请求的输出缓冲区。
语法
NTSTATUS WdfRequestRetrieveOutputBuffer(
[in] WDFREQUEST Request,
[in] size_t MinimumRequiredSize,
[out] PVOID *Buffer,
[out, optional] size_t *Length
);
参数
[in] Request
框架请求对象的句柄。
[in] MinimumRequiredSize
驱动程序处理 I/O 请求所需的最小缓冲区大小（以字节为单位）。
[out] Buffer
指向接收缓冲区地址的位置的指针。
[out, optional] Length
指向接收缓冲区大小（以字节为单位）的位置的指针。 此参数是可选的，可以 NULL。
返回值
WdfRequestRetrieveOutputBuffer 如果作成功，则返回STATUS_SUCCESS。 否则，此方法可能会返回以下值之一：
| 返回代码 | 描述 |
|---|---|
|
输入参数无效。 |
|
输出缓冲区的长度为零，或者 MinimumRequiredSize 参数指定大于缓冲区的实际大小的缓冲区大小。 |
|
请求类型无效，或者请求未使用 缓冲或直接 I/O。 有关访问数据缓冲区支持的方法的详细信息，请参阅以下“备注”部分。 |
|
请求已完成。 |
|
内存不足。 |
此方法也可能返回其他 NTSTATUS 值。
如果驱动程序提供无效的对象句柄，则会发生 bug 检查。
言论
请求的输出缓冲区接收来自磁盘的数据等信息，驱动程序提供给请求的发起方。 驱动程序可以调用 WdfRequestRetrieveOutputBuffer 以获取读取请求或设备 I/O 控制请求的输出缓冲区，但不能用于写入请求（因为写入请求不提供输出数据）。
WdfRequestRetrieveOutputBuffer 方法检索使用 缓冲 I/O 方法或用于访问数据缓冲区的 直接 I/O 方法的 I/O 请求的输出缓冲区。 如果请求的 I/O 控制代码 IRP_MJ_INTERNAL_DEVICE_CONTROL，或者如果请求来自另一个内核模式驱动程序，WdfRequestRetrieveOutputBuffer 也支持使用 未缓冲的 I/O 请求，也不支持直接 I/O。
如果 WdfRequestRetrieveOutputBuffer 返回STATUS_SUCCESS，驱动程序将接收地址，并且（可选）接收输出缓冲区的大小。
驱动程序可以访问检索到的缓冲区，直到 完成 请求 参数表示的 I/O 请求。
驱动程序可以调用 WdfRequestRetrieveOutputMemory，从而创建表示缓冲区的框架内存对象，而不是调用 WdfRequestRetrieveOutputBuffer。
有关 WdfRequestRetrieveOutputBuffer的详细信息，请参阅 访问 Framework-Based 驱动程序中的数据缓冲区。
例子
以下代码示例是 EvtIoDeviceControl 回调函数的一部分。 此示例获取 USB 设备的配置描述符，并将描述符置于 I/O 请求的输出缓冲区中。
VOID
MyEvtIoDeviceControl(
IN WDFQUEUE Queue,
IN WDFREQUEST Request,
IN size_t OutputBufferLength,
IN size_t InputBufferLength,
IN ULONG IoControlCode
)
{
WDFDEVICE device;
PDEVICE_CONTEXT pDevContext;
size_t bytesReturned = 0;
NTSTATUS status;
device = WdfIoQueueGetDevice(Queue);
//
// GetDeviceContext is a driver-defined function
// to retrieve device object context space.
//
pDevContext = GetDeviceContext(device);
switch(IoControlCode) {
case IOCTL_OSRUSBFX2_GET_CONFIG_DESCRIPTOR: {
PUSB_CONFIGURATION_DESCRIPTOR configurationDescriptor = NULL;
USHORT requiredSize;
//
// First, get the size of the USB configuration descriptor.
//
status = WdfUsbTargetDeviceRetrieveConfigDescriptor(
pDevContext->UsbDevice,
NULL,
&requiredSize
);
if (status == STATUS_BUFFER_TOO_SMALL) {
break;
}
//
// Get the buffer. Make sure the buffer is big
// enough to hold the configuration descriptor.
//
status = WdfRequestRetrieveOutputBuffer(
Request,
(size_t)requiredSize,
&configurationDescriptor,
NULL
);
if(!NT_SUCCESS(status)){
break;
}
//
// Now get the config descriptor.
//
status = WdfUsbTargetDeviceRetrieveConfigDescriptor(
pDevContext->UsbDevice,
configurationDescriptor,
&requiredSize
);
if (!NT_SUCCESS(status)) {
break;
}
bytesReturned = requiredSize;
}
break;
...
(Other case statements removed.)
...
default:
status = STATUS_INVALID_DEVICE_REQUEST;
break;
}
//
// Complete the request.
//
WdfRequestCompleteWithInformation(
Request,
status,
bytesReturned
);
return;
}
要求
| 要求 | 价值 |
|---|---|
| 目标平台 | 普遍 |
| 最低 KMDF 版本 | 1.0 |
| 最低 UMDF 版本 | 2.0 |
| 标头 | wdfrequest.h （包括 Wdf.h） |
| 库 | Wdf01000.sys（KMDF）：WUDFx02000.dll （UMDF） |
| IRQL | <=DISPATCH_LEVEL |
| DDI 符合性规则 | BufAfterReqCompletedIntIoctl（kmdf），BufAfterReqCompletedIntIoctlA（kmdf），BufAfterReqCompletedIoctl（kmdf），BufAfterReqCompletedIoctlA（kmdf），BufAfterReqCompletedRead（kmdf），BufAfterReqCompletedReadA（kmdf）， BufAfterReqCompletedWrite（kmdf）， DriverCreate（kmdf）， InvalidReqAccess（kmdf）， InvalidReqAccessLocal（kmdf）， KmdfIrql（kmdf）， KmdfIrql2（kmdf）， KmdfIrqlExplicit（kmdf）， OutputBufferAPI（kmdf） |