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

  • Статья

[Относится к KMDF и UMDF]

Метод WdfRequestRetrieveInputBuffer извлекает входной буфер запроса ввода-вывода.

Синтаксис

NTSTATUS WdfRequestRetrieveInputBuffer(
  [in]            WDFREQUEST Request,
                  size_t     MinimumRequiredLength,
  [out]           PVOID      *Buffer,
  [out, optional] size_t     *Length
);

Параметры

[in] Request

Дескриптор объекта запроса платформы.

MinimumRequiredLength

Минимальный размер буфера (в байтах), необходимый драйверу для обработки запроса ввода-вывода.

[out] Buffer

Указатель на расположение, которое получает адрес буфера.

[out, optional] Length

Указатель на расположение, которое получает размер буфера в байтах. Этот параметр является необязательным и может иметь значение NULL.

Возвращаемое значение

WdfRequestRetrieveInputBuffer возвращает STATUS_SUCCESS, если операция выполнена успешно. В противном случае этот метод может вернуть одно из следующих значений:

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

Этот метод также может возвращать другие значения NTSTATUS.

Ошибка проверка возникает, если драйвер предоставляет недопустимый дескриптор объекта.

Комментарии

Входной буфер запроса содержит сведения, например данные для записи на диск, предоставленные инициатором запроса. Драйвер может вызвать WdfRequestRetrieveInputBuffer , чтобы получить входной буфер для запроса на запись или запроса управления вводом-выводом устройства, но не для запроса на чтение (так как запросы на чтение не предоставляют входные данные).

Метод WdfRequestRetrieveInputBuffer извлекает входной буфер для запросов ввода-вывода, использующих метод буферизованного ввода-вывода или прямой метод ввода-вывода для доступа к буферам данных. Если код элемента управления вводом-выводом запроса IRP_MJ_INTERNAL_DEVICE_CONTROL или запрос поступил из другого драйвера режима ядра, WdfRequestRetrieveInputBuffer также поддерживает запросы ввода-вывода, которые не используют ни буферизованных, ни прямых операций ввода-вывода.

Если WdfRequestRetrieveInputBuffer возвращает STATUS_SUCCESS, драйвер получает адрес и, при необходимости, размер входного буфера.

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

Вместо вызова WdfRequestRetrieveInputBuffer драйвер может вызвать WdfRequestRetrieveInputMemory, который создает объект памяти платформы, представляющий буфер.

Дополнительные сведения о WdfRequestRetrieveInputBuffer см. в статье Доступ к буферам данных в драйверах Framework-Based.

Примеры

Следующий пример кода является частью функции обратного вызова EvtIoDeviceControl драйвера Serial. Если код элемента управления вводом-выводом IOCTL_SERIAL_SET_TIMEOUT, драйвер получает новые значения времени ожидания из входного буфера запроса ввода-вывода.

VOID
SerialEvtIoDeviceControl(
    IN WDFQUEUE     Queue,
    IN WDFREQUEST   Request,
    IN size_t       OutputBufferLength,
    IN size_t       InputBufferLength,
    IN ULONG        IoControlCode
    )
{
    PVOID  buffer;
    size_t  bufSize;

    switch (IoControlCode) {
...

        case IOCTL_SERIAL_SET_TIMEOUTS: {

            PSERIAL_TIMEOUTS NewTimeouts;

            Status = WdfRequestRetrieveInputBuffer(
                                                   Request,
                                                   sizeof(SERIAL_TIMEOUTS),
                                                   &buffer,
                                                   &bufSize
                                                   );
            if (!NT_SUCCESS(Status)) {
                break;
            }

            NewTimeouts =(PSERIAL_TIMEOUTS)buffer;
    }
...
}

Требования

Требование Значение
Целевая платформа Универсальное
Минимальная версия 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), BufAfterReqCompletedWrite(kmdf), BufAfterReqCompletedWriteA(kmdf), DriverCreate(kmdf), InputBufferAPI(kmdf), InvalidReqAccess(kmdf), InvalidReqAccessLocal(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)

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

WdfRequestRetrieveInputMemory

WdfRequestRetrieveOutputBuffer

WdfUsbTargetDeviceRetrieveConfigDescriptor