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，也不使用直接 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 的 I/O 请求。
如果 WdfRequestRetrieveOutputBuffer 返回STATUS_SUCCESS，驱动程序将接收地址以及输出缓冲区的大小（可选）。
驱动程序可以访问检索到的缓冲区，直到它完成 Request 参数表示的 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) |
| Library | Wdf01000.sys (KMDF) ;WUDFx02000.dll (UMDF) |
| IRQL | <=DISPATCH_LEVEL |
| DDI 符合性规则 | BufAfterReqCompletedIntIoctl (kmdf) 、 BufAfterReqCompletedIntIoctlA (kmdf) 、 BufAfterReqCompletedIoctl (kmdf) 、 BufAfterReqCompletedIoctlA (kmdf) 、 BufAfterReqCompleted (Read kmdf) 、 BufAfterReqCompletedReadA (kmdf) 、 BufAfterReqCompletedWrite (kmdf) 、 DriverCreate (kmdf) 、 InvalidReqAccess (kmdf) 、 InvalidReqAccessLocal (kmdf) 、 KmdfIrql (kmdf) 、 KmdfIrql2 (kmdf) 、KmdfIrqlExplicit (kmdf) 、 OutputBufferAPI (kmdf) |