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

Статья
08/08/2023

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

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

Синтаксис

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

Параметры

[in] MinimumRequiredCb

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

[out] Buffer

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

[out, optional] BufferCb

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

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

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

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

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

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

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

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

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

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

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

Примеры

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

VOID
STDMETHODCALLTYPE
  CMyQueue::OnDeviceIoControl(
    __in IWDFIoQueue *pWdfQueue,
    __in IWDFIoRequest *pWdfRequest,
    __in ULONG ControlCode,
    __in SIZE_T InputBufferSizeInBytes,
    __in SIZE_T OutputBufferSizeInBytes
    )
{
    HRESULT hr;
    //
    // Declare an IWDFIoRequest2 interface pointer and obtain the
    // IWDFIoRequest2 interface from the IWDFIoRequest interface.
    //
    CComQIPtr<IWDFIoRequest2> r2 = pWdfRequest;

    switch (ControlCode)
    {
        case IOCTL_SERIAL_GET_BAUD_RATE:
        {
            SERIAL_BAUD_RATE *pBaudRateBuffer;
            hr = pWdfRequest2->RetrieveOutputBuffer(sizeof(SERIAL_BAUD_RATE),
                                                    (PVOID*) &pBaudRateBuffer,
                                                    NULL);
            if (SUCCEEDED(hr))
                  {
                      RtlZeroMemory(pBaudRateBuffer, sizeof(SERIAL_BAUD_RATE));
                      pBaudRateBuffer->BaudRate = m_Device->GetBaudRate();
                      reqCompletionInfo = sizeof(SERIAL_BAUD_RATE);
                  }
            
        }
        break;
        ...
    }
    ...
}

Требования

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