Метод IWDFIoRequest2::RetrieveInputBuffer (wudfddi.h)

Статья
08/08/2023

[Предупреждение: UMDF 2 является последней версией UMDF и заменяет UMDF 1. Все новые драйверы UMDF должны быть написаны с помощью UMDF 2. В UMDF 1 новые функции не добавляются, а поддержка UMDF 1 в более новых версиях Windows 10 ограничена. Универсальные драйверы Windows должны использовать UMDF 2. Дополнительные сведения см. в разделе начало работы с UMDF.]

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

Синтаксис

HRESULT RetrieveInputBuffer(
  [in]            SIZE_T MinimumRequiredCb,
  [out]           PVOID  *Buffer,
  [out, optional] SIZE_T *BufferCb
);

Параметры

[in] MinimumRequiredCb

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

[out] Buffer

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

[out, optional] BufferCb

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

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

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

Код возврата	Описание
HRESULT_FROM_WIN32(ERROR_INSUFFICIENT_BUFFER)	Запрос ввода-вывода не предоставил входной буфер, или размер входного буфера меньше минимального размера, указанного MinimumRequiredCb .
E_OUTOFMEMORY	Недостаточно памяти для извлечения буфера. Драйвер должен завершить запрос со значением состояния ошибки.

Этот метод может возвращать одно из других значений, содержащихся в Winerror.h.

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

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

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

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

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

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

Примеры

В следующем примере кода показан сегмент функции обратного вызова IQueueCallbackDeviceIoControl::OnDeviceIoControl драйвера последовательных портов. Из входного буфера запроса ввода-вывода сегмент кода получает скорость передачи данных, которая должна быть задана для устройства.

VOID
STDMETHODCALLTYPE
  CMyQueue::OnDeviceIoControl(
    __in IWDFIoQueue*  FxQueue,
    __in IWDFIoRequest*  FxRequest,
    __in ULONG  ControlCode,
    __in SIZE_T  InputBufferCb,
    __in SIZE_T  OutputBufferCb
    )
{
    PBYTE buffer;
    SIZE_T bufferSize;
    HRESULT hr;
    //
    // Declare an IWDFIoRequest2 interface pointer and obtain the
    // IWDFIoRequest2 interface from the IWDFIoRequest interface.
    //
    CComQIPtr<IWDFIoRequest2> r2 = FxRequest;

    switch (ControlCode)
    {
        case IOCTL_SERIAL_SET_BAUD_RATE: 
        {
            //
            // Obtain the baud rate from the write request's input buffer.
            //
            hr = r2->RetrieveInputBuffer(sizeof(SERIAL_BAUD_RATE),
                                         (PVOID*) &buffer, 
                                         &bufferSize);
...
        }
    }
}

Требования

Требование	Значение
Дата окончания поддержки	Недоступно в UMDF 2.0 и более поздних версиях.
Целевая платформа	Персональный компьютер
Минимальная версия UMDF	1,9
Верхняя часть	wudfddi.h (включая Wudfddi.h)
DLL	WUDFx.dll