WdfRequestRetrieveOutputMemory 函式 (wdfrequest.h)

  • 發行項

[適用於 KMDF 和 UMDF]

WdfRequestRetrieveOutputMemory 方法會擷取架構記憶體物件的句柄，該物件代表 I/O 要求的輸出緩衝區。

語法

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

參數

[in] Request

架構要求物件的句柄。

[out] Memory

接收架構記憶體物件句柄之位置的指標。

傳回值

如果作業成功，WdfRequestRetrieveOutputMemory 會傳回STATUS_SUCCESS。 否則，這個方法可能會傳回下列其中一個值：

傳回碼 Description
STATUS_INVALID_PARAMETER
 輸入參數無效。
STATUS_INVALID_DEVICE_REQUEST
 要求類型無效，或要求 未使用緩衝處理或直接 I/O。 如需有關存取數據緩衝區之支援方法的詳細資訊，請參閱下列一節。
STATUS_INTERNAL_ERROR
 要求已經完成。
STATUS_BUFFER_TOO_SMALL
 輸出緩衝區的長度為零。
STATUS_INSUFFICIENT_RESOURCES
 記憶體不足。
 

這個方法也可能傳回其他 NTSTATUS值。

如果驅動程式提供無效的物件句柄，就會發生錯誤檢查。

備註

要求的輸出緩衝區會接收來自磁碟的數據等資訊，驅動程式會提供給要求的來源。 驅動程式可以呼叫 WdfRequestRetrieveOutputMemory 來取得讀取要求或裝置 I/O 控制要求的輸出緩衝區，但不適用於寫入要求 (，因為寫入要求不會提供輸出數據) 。

WdfRequestRetrieveOutputMemory 方法會擷取 I/O 要求的輸出緩衝區，這些要求會使用緩衝的 I/O 方法或直接 I/O 方法來存取數據緩衝區。 如果要求的 I/O 控制程式代碼 IRP_MJ_INTERNAL_DEVICE_CONTROL，或要求來自另一個內核模式驅動程式， WdfRequestRetrieveOutputMemory 也支援使用 未緩衝或直接 I/O 的 I/O 要求。

如果 WdfRequestRetrieveOutputMemory 傳回STATUS_SUCCESS，驅動程式就會收到代表輸出緩衝區之架構記憶體物件的句柄。 若要存取緩衝區，驅動程式必須呼叫 WdfMemoryGetBuffer。

驅動程式可以存取擷取的架構記憶體物件，直到它完成 Request 參數所代表的 I/O 要求為止。

驅動程式可以呼叫 WdfRequestRetrieveOutputBuffer，而不是呼叫 WdfRequestRetrieveOutputBuffer，以擷取緩衝區的位址和長度。

如需 WdfRequestRetrieveOutputMemory 的詳細資訊，請參閱 存取 Framework-Based 驅動程式中的數據緩衝區。

範例

下列程式代碼範例示範 EvtIoRead 回呼函式如何取得架構記憶體物件的句柄，該物件代表讀取要求的輸出緩衝區。 此範例接著會將讀取要求格式化並傳送至USB I/O目標。

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;
}

規格需求

需求 值
目標平台 Universal
最低 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