Функция WdfRequestRetrieveOutputBuffer (wdfrequest.h)

Статья
08/08/2023

[Применимо к 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, драйвер получает адрес и, при необходимости, размер выходного буфера.

Драйвер может получить доступ к полученному буферу, пока не завершит запрос ввода-вывода, который представляет параметр запроса.

Вместо вызова 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

Поделиться через