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

Статья
08/08/2023

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

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

Синтаксис

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

Параметры

[in] Request

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

[out] Memory

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

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

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

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

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

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

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

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

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

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

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

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

Примеры

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

VOID 
MyEvtIoRead(
    IN WDFQUEUE  Queue,
    IN WDFREQUEST  Request,
    IN size_t  Length
    )
{
    WDFUSBPIPE  pipe;
    NTSTATUS  status;
    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->BulkReadPipe;

    //
    // Get output memory.
    //
    status = WdfRequestRetrieveOutputMemory(
                                            Request,
                                            &reqMemory
                                            );
    if(!NT_SUCCESS(status)){
        goto Exit;
    }
    //
    // Format the request.
    //
    status = WdfUsbTargetPipeFormatRequestForRead(
                                           pipe,
                                           Request,
                                           reqMemory,
                                           NULL
                                           ); 
    if (!NT_SUCCESS(status)) {
        goto Exit;
    }
    WdfRequestSetCompletionRoutine(
                                   Request,
                                   EvtRequestReadCompletionRoutine,
                                   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), InvalidReqAccess(kmdf), InvalidReqAccessLocal(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), MemAfterReqCompletedIntIoctl(kmdf), MemAfterReqCompletedIntIoctlA(kmdf), MemAfterReqCompletedIoctl(kmdf), MemAfterReqCompletedIoctlA(kmdf), MemAfterReqCompletedRead(kmdf), MemAfterReqCompletedReadA(kmdf), MemAfterReqCompletedWrite(kmdf), OutputBufferAPI(kmdf)

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

WdfMemoryGetBuffer

WdfRequestRetrieveInputMemory

WdfRequestRetrieveOutputBuffer

Поделиться через