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

Статья
08/08/2023

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

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

Синтаксис

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

Параметры

[out] Memory

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

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

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

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

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

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

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

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

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

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

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

Примеры

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

VOID
STDMETHODCALLTYPE
  CMyQueue::OnWrite(
    __in IWDFIoQueue *pWdfQueue,
    __in IWDFIoRequest *pWdfRequest,
    __in SIZE_T BytesToWrite
    )
{
    HRESULT hr = S_OK;
    IWDFMemory * pInputMemory = NULL;
    IWDFUsbTargetPipe * pOutputPipe = m_Device->GetOutputPipe();
    //
    // Declare an IWDFIoRequest2 interface pointer and obtain the
    // IWDFIoRequest2 interface from the IWDFIoRequest interface.
    //
    CComQIPtr<IWDFIoRequest2> r2 = pWdfRequest;

    hr = r2->RetrieveInputMemory(&pInputMemory);
    if (FAILED(hr)) goto Exit;

    hr = pOutputPipe->FormatRequestForWrite(
                                           pWdfRequest,
                                           NULL, //pFile
                                           pInputMemory,
                                           NULL, //Memory offset
                                           NULL  //DeviceOffset
                                           );
Exit:
    if (FAILED(hr))
    {
        pWdfRequest->Complete(hr);
    }
    else
    {
        ForwardFormattedRequest(pWdfRequest, pOutputPipe);
    }
    SAFE_RELEASE(pInputMemory);
 return;
}

Требования

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