Функция WdfRequestRetrieveInputMemory (wdfrequest.h)

[Применимо к KMDF и UMDF]

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

Синтаксис

NTSTATUS WdfRequestRetrieveInputMemory(
  [in]  WDFREQUEST Request,
  [out] WDFMEMORY  *Memory
);

Параметры

[in] Request

Дескриптор объекта запроса платформы.

[out] Memory

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

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

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

Код возврата	Описание
STATUS_INVALID_PARAMETER	Недопустимый входной параметр.
STATUS_INVALID_DEVICE_REQUEST	Недопустимый тип запроса или запрос не использует ни буферизированный, ни прямой ввод-вывод. Дополнительные сведения о поддерживаемых методах доступа к буферам данных см. в следующем разделе Примечаний.
STATUS_INTERNAL_ERROR	Запрос уже завершен.
STATUS_BUFFER_TOO_SMALL	Длина входного буфера равна нулю.
STATUS_INSUFFICIENT_RESOURCES	Недостаточно памяти.

 

Этот метод также может возвращать другие значения NTSTATUS.

Ошибка проверка возникает, если драйвер предоставляет недопустимый дескриптор объекта.

Комментарии

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

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

Если WdfRequestRetrieveInputMemory возвращает STATUS_SUCCESS, драйвер получает дескриптор объекта памяти платформы, который представляет входной буфер. Чтобы получить доступ к буферу, драйвер должен вызвать WdfMemoryGetBuffer.

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

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

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

Примеры

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

VOID 
MyEvtIoWrite(
    IN WDFQUEUE  Queue,
    IN WDFREQUEST  Request,
    IN size_t  Length
    )
{
    NTSTATUS  status;
    WDFUSBPIPE  pipe;
    WDFMEMORY  reqMemory;
    PDEVICE_CONTEXT  pDeviceContext;

    //
    // The driver previously stored a pipe handle in 
    // the device object's context space.
    //
    pDeviceContext = GetDeviceContext(WdfIoQueueGetDevice(Queue));
    pipe = pDeviceContext->BulkWritePipe;

    //
    // Get input memory.
    //
    status = WdfRequestRetrieveInputMemory(
                                           Request,
                                           &reqMemory
                                           );
    if(!NT_SUCCESS(status)){
        goto Exit;
    }

    //
    // Format the request.
    //
    status = WdfUsbTargetPipeFormatRequestForWrite(
                                          pipe,
                                          Request,
                                          reqMemory,
                                          NULL
                                          );
    if (!NT_SUCCESS(status)) {
        goto Exit;
    }
    WdfRequestSetCompletionRoutine(
                                   Request,
                                   EvtRequestWriteCompletionRoutine,
                                   pipe
                                   );

    //
    // Send the request.
    //
    if (WdfRequestSend(
                       Request,
                       WdfUsbTargetPipeGetIoTarget(pipe),
                       WDF_NO_SEND_OPTIONS
                       ) == FALSE) {
        status = WdfRequestGetStatus(Request);
        goto Exit;
    }
Exit:
    //
    // Complete the request now if an error occurred.
    //
    if (!NT_SUCCESS(status)) {
        WdfRequestCompleteWithInformation(
                                          Request,
                                          status,
                                          0
                                          );
    }
    return;
}

Требования

Требование	Значение
Целевая платформа	Универсальное
Минимальная версия KMDF	1,0
Минимальная версия UMDF	2,0
Верхняя часть	wdfrequest.h (включая Wdf.h)
Библиотека	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL	<=DISPATCH_LEVEL
Правила соответствия DDI	DriverCreate(kmdf), InputBufferAPI(kmdf), InvalidReqAccess(kmdf), InvalidReqAccessLocal(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), MemAfterReqCompletedIntIoctl(kmdf), MemAfterReqCompletedIntIoctlA(kmdf), MemAfterReqCompletedIoctl(kmdf), MemAfterReqCompletedIoctlA(kmdf), MemAfterReqCompletedRead(kmdf), MemAfterReqCompletedWrite(kmdf) , MemAfterReqCompletedWriteA(kmdf)

См. также раздел

WdfMemoryGetBuffer

WdfRequestRetrieveInputBuffer

WdfRequestRetrieveOutputMemory