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

Статья
08/08/2023

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

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

Синтаксис

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

Параметры

[out] Memory

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

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

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

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

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

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

Метод 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 (включая Wudfddi.h)
DLL	WUDFx.dll