WdfRequestComplete 函式 (wdfrequest.h)

發行項
02/27/2024

[適用於 KMDF 和 UMDF]

WdfRequestComplete 方法會完成指定的 I/O 要求，並提供完成狀態。

語法

void WdfRequestComplete(
  [in] WDFREQUEST Request,
  [in] NTSTATUS   Status
);

參數

[in] Request

架構要求物件的句柄，表示正在完成的 I/O 要求。

[in] Status

NTSTATUS 值，表示要求的完成狀態。有效的狀態值包括但不限於下列各項：

STATUS_SUCCESS

驅動程式已成功完成要求。

STATUS_CANCELLED

驅動程式正在取消要求。

STATUS_UNSUCCESSFUL

驅動程式在處理要求時發生錯誤。

傳回值

無

備註

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

在驅動程式呼叫 WdfRequestComplete 之後，驅動程式堆疊上的較高層級驅動程式可以呼叫 WdfRequestGetStatus ，以取得為 Status 參數指定的完成狀態值。一般而言，驅動程式會從 CompletionRoutine 回呼函式內呼叫 WdfRequestGetStatus。

呼叫 WdfRequestComplete 之後，除非驅動程式已呼叫 WdfObjectReference ，否則要求句柄已不再有效，以將一或多個額外的參考計數新增至要求物件。請注意， 在 WdfRequestComplete 傳回之後，驅動程式不得嘗試存取相關聯的 WDM IRP 結構，即使它已呼叫 WdfObjectReference 也一樣。這項需求可藉由在 WDFREQUEST 上呼叫方法，例如 WdfRequestRetrieveOutputBuffer 或 WdfRequestRetrieveInputBuffer 來存取相關聯的 WDM IRP 結構。

驅動程式呼叫 WdfRequestComplete 之後，如果驅動程式已提供，架構會針對要求呼叫驅動程式的 EvtCleanupCallback 函式。

驅動程式可以呼叫 WdfRequestCompleteWithInformation 或 WdfRequestCompleteWithPriorityBoost，而不是呼叫 WdfRequestComplete。如需詳細資訊，請參閱 WdfRequestCompleteWithInformation 的備註。

當您的驅動程式呼叫 WdfRequestComplete 時，架構會提供預設值，讓系統用來提升要求 I/O 作業之線程的運行時間優先順序。如需預設優先順序提升值的相關信息，請參閱完成 I/O 要求時指定優先順序提升。您的驅動程式可以呼叫 WdfRequestCompleteWithPriorityBoost 來覆寫預設優先順序提升值。

如需呼叫 WdfRequestComplete 的詳細資訊，請參閱完成 I/O 要求。

範例

下列程式代碼範例是要求處理程式的區段。要求處理程式只接受讀取和寫入要求，如果要求類型不是讀取或寫入，則會完成具有錯誤狀態的每個要求。

VOID
MyEvtIoDefault(
    IN WDFQUEUE  Queue,
    IN WDFREQUEST  Request
    )
{
    WDF_REQUEST_PARAMETERS  params;
    WDF_DMA_DIRECTION  direction;

...
    WDF_REQUEST_PARAMETERS_INIT(&params);

    WdfRequestGetParameters(
                            Request,
                            &params
                            );

    //
    // Validate and gather parameters.
    //
    switch (params.Type) {
        case WdfRequestTypeRead:
            length = params.Parameters.Read.Length;
            direction = WdfDmaDirectionReadFromDevice;
            break;
        case WdfRequestTypeWrite:
            length = params.Parameters.Write.Length;
            direction = WdfDmaDirectionWriteToDevice;
            break;
        default:
            WdfRequestComplete(
                               Request,
                               STATUS_INVALID_DEVICE_REQUEST
                               );
            return;
    }
...
}

規格需求

需求	值
目標平台	Universal
最低 KMDF 版本	1.0
最低UMDF版本	2.0
標頭	wdfrequest.h (包含 Wdf.h)
程式庫	Wdf01000.sys (KMDF) ;WUDFx02000.dll (UMDF)
IRQL	<=DISPATCH_LEVEL
DDI 合規性規則	BufAfterReqCompletedIntIoctl (kmdf) 、 BufAfterReqCompletedIntIoctlA (kmdf) 、 BufAfterReqCompletedIoctl (kmdf ) 、 BufAfterReqCompletedIoctlA (kmdf) 、 BufAfterReqCompletedRead (kmdf) 、BufAfterReqCompletedReadA (kmdf) 、BufAfterReqCompletedWrite (kmdf) 、BufAfterReqCompletedWriteA (kmdf) 、CompleteCanceledReq (kmdf) 、 DeferredRequestCompleted (kmdf) 、DoubleCompletion (kmdf) 、DoubleCompletionLocal (kmdf) 、DriverCreate (kmdf) 、EvtIoStopCancel (kmdf) 、EvtIoStopCompleteOrStopAck (kmdf) 、EvtSurpriseRemoveNoRequestComplete (kmdf) 、InvalidReqAccess (kmdf) 、KmdfIrql (kmdf) 、KmdfIrql2 (kmdf) 、KmdfIrqlExplicit (kmdf) 、MarkCancOnCancReqLocal (kmdf) 、 MdlAfterReqCompletedIntIoctl (kmdf) 、 MdlAfterReqCompletedIntIoctlA (kmdf) 、 MdlAfterReqCompletedIoctl (kmdf) 、 MdlAfterReqCompleted IoctlA (kmdf) 、 MdlAfterReqCompletedRead (kmdf) 、 MdlAfterReqCompletedReadA (kmdf) 、 MdlAfterReqCompletedW (rite) 、 MdlAfterReqCompletedWriteA (kmdf) 、 MemAfterReqCompletedIntIoctl (kmdf) 、 MemAfterReqCompletedIntIoctlA (kmdf) 、 MemAfterReqCompletedIoct (l ) 、 MemAfterReqCompletedIoctlA (kmdf) 、 MemAfterReqCompletedRead (kmdf) 、MemAfterReqCompletedReadA (kmdf) 、MemAfterReqCompletedWrite (kmdf) 、MemAfterReqCompletedWriteA (kmdf) 、NoCancelFromEvtSurpriseRemove (kmdf) 、 ReqDelete (kmdf) 、 ReqIsCancOnCancOnCancReq (kmdf) 、 ReqNotCanceledLocal (kmdf) 、 ReqSendFail (kmdf ) 、 RequestComplet (ed ) 、 RequestCompletedLocal (kmdf)