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

Статья
02/07/2025

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

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

Синтаксис

HRESULT RetrieveOutputMemory(
  [out] IWDFMemory **Memory
);

Параметры

[out] Memory

Адрес расположения, получающего указатель на интерфейс IWDFMemory объекта памяти UMDF.

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

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

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

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

Замечания

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

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

Если RetrieveOutputMemory возвращает S_OK, драйвер получает указатель на интерфейс IWDFMemory объекта памяти UMDF, представляющего выходной буфер. Чтобы получить доступ к буферу, драйвер должен вызвать IWDFMemory::GetDataBuffer.

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

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

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

Примеры

В следующем примере кода показано, как функция обратного вызова IQueueCallbackRead::OnRead может получить интерфейс IWDFMemory интерфейса объекта памяти платформы, представляющего выходной буфер запроса на чтение. Затем пример форматирует и отправляет запрос на чтение в целевой объект usb-ввода-вывода.

VOID
STDMETHODCALLTYPE
  CMyQueue::OnRead(
     __in IWDFIoQueue *pWdfQueue,
     __in IWDFIoRequest *pWdfRequest,
     __in SIZE_T BytesToRead
     )
{
    HRESULT hr = S_OK;
    IWDFMemory * pOutputMemory = NULL;

    //
    // Declare an IWDFIoRequest2 interface pointer and obtain the
    // IWDFIoRequest2 interface from the IWDFIoRequest interface.
    //
    CComQIPtr<IWDFIoRequest2> r2 = pWdfRequest;

    r2->RetrieveOutputMemory(&pOutputMemory);
    if (FAILED(hr)) goto Exit;

    hr = m_Device->GetInputPipe()->FormatRequestForRead(pWdfRequest,
                                                        NULL,
                                                        pOutputMemory,
                                                        NULL,
                                                        NULL);
Exit:
    if (FAILED(hr))
    {
        pWdfRequest->Complete(hr);
    }
    else
    {
        ForwardFormattedRequest(pWdfRequest, m_Device->GetInputPipe());
    }
    SAFE_RELEASE(pOutputMemory);
    return;
}

Требования

Требование	Ценность
завершение поддержки	Недоступно в UMDF 2.0 и более поздних версиях.
целевая платформа	Настольный
минимальная версия UMDF	1.9
заголовка	wudfddi.h (include Wudfddi.h)
DLL	WUDFx.dll