Функция WdfRequestRetrieveOutputBuffer (wdfrequest.h)
[Применимо к KMDF и UMDF]
Метод WdfRequestRetrieveOutputBuffer извлекает выходной буфер запроса ввода-вывода.
Синтаксис
NTSTATUS WdfRequestRetrieveOutputBuffer(
[in] WDFREQUEST Request,
[in] size_t MinimumRequiredSize,
[out] PVOID *Buffer,
[out, optional] size_t *Length
);
Параметры
[in] Request
Дескриптор объекта запроса платформы.
[in] MinimumRequiredSize
Минимальный размер буфера в байтах, необходимый драйверу для обработки запроса ввода-вывода.
[out] Buffer
Указатель на расположение, которое получает адрес буфера.
[out, optional] Length
Указатель на расположение, которое получает размер буфера в байтах. Этот параметр является необязательным и может иметь значение NULL.
Возвращаемое значение
WdfRequestRetrieveOutputBuffer возвращает STATUS_SUCCESS, если операция выполнена успешно. В противном случае этот метод может возвращать одно из следующих значений:
Код возврата | Описание |
---|---|
|
Недопустимый входной параметр. |
|
Длина выходного буфера равна нулю, или параметр MinimumRequiredSize указывает размер буфера, превышающий фактический размер буфера. |
|
Недопустимый тип запроса или запрос не использует ни буферизированный, ни прямой ввод-вывод. Дополнительные сведения о поддерживаемых методах доступа к буферам данных см. в следующем разделе Примечаний. |
|
Запрос уже завершен. |
|
Недостаточно памяти. |
Этот метод также может возвращать другие значения NTSTATUS.
Ошибка проверка возникает, если драйвер предоставляет недопустимый дескриптор объекта.
Комментарии
Выходной буфер запроса получает информацию, например данные с диска, которую драйвер предоставляет инициатору запроса. Драйвер может вызвать WdfRequestRetrieveOutputBuffer , чтобы получить выходной буфер для запроса на чтение или запроса управления вводом-выводом устройства, но не для запроса на запись (так как запросы на запись не предоставляют выходные данные).
Метод WdfRequestRetrieveOutputBuffer извлекает выходной буфер для запросов ввода-вывода, использующих метод буферизованного ввода-вывода или прямой метод ввода-вывода для доступа к буферам данных. Если код элемента управления вводом-выводом запроса IRP_MJ_INTERNAL_DEVICE_CONTROL или запрос поступил от другого драйвера режима ядра, WdfRequestRetrieveOutputBuffer также поддерживает запросы ввода-вывода, которые не используют ни буферизованные, ни прямые операции ввода-вывода.
Если WdfRequestRetrieveOutputBuffer возвращает STATUS_SUCCESS, драйвер получает адрес и, при необходимости, размер выходного буфера.
Драйвер может получить доступ к полученному буферу, пока не завершит запрос ввода-вывода , который представляет параметр Request .
Вместо вызова WdfRequestRetrieveOutputBuffer драйвер может вызвать WdfRequestRetrieveOutputMemory, который создает объект памяти платформы, представляющий буфер.
Дополнительные сведения о WdfRequestRetrieveOutputBuffer см. в разделе Доступ к буферам данных в драйверах Framework-Based.
Примеры
Следующий пример кода является частью функции обратного вызова EvtIoDeviceControl . В этом примере получается дескриптор конфигурации USB-устройства и дескриптор помещает его в выходной буфер запроса ввода-вывода.
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) |