Функция 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, если операция выполнена успешно. В противном случае этот метод может возвращать одно из следующих значений:

Код возврата	Описание
STATUS_INVALID_PARAMETER	Недопустимый входной параметр.
STATUS_BUFFER_TOO_SMALL	Длина выходного буфера равна нулю, или параметр MinimumRequiredSize указывает размер буфера, превышающий фактический размер буфера.
STATUS_INVALID_DEVICE_REQUEST	Недопустимый тип запроса или запрос не использует ни буферизированный, ни прямой ввод-вывод. Дополнительные сведения о поддерживаемых методах доступа к буферам данных см. в следующем разделе Примечаний.
STATUS_INTERNAL_ERROR	Запрос уже завершен.
STATUS_INSUFFICIENT_RESOURCES	Недостаточно памяти.

 

Этот метод также может возвращать другие значения 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)

См. также раздел

WdfRequestRetrieveInputBuffer

WdfRequestRetrieveOutputMemory