WdfRequestCompleteWithInformation 函式 (wdfrequest.h)

發行項
03/01/2024

[適用於 KMDF 和 UMDF]

WdfRequestCompleteWithInformation 方法會儲存完成資訊，然後完成具有提供完成狀態的指定 I/O 要求。

語法

void WdfRequestCompleteWithInformation(
  [in] WDFREQUEST Request,
  [in] NTSTATUS   Status,
  [in] ULONG_PTR  Information
);

參數

[in] Request

要求物件的句柄。

[in] Status

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

STATUS_SUCCESS

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

STATUS_CANCELLED

驅動程式已取消要求。

STATUS_UNSUCCESSFUL

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

[in] Information

設定為要求相依值的ULONG_PTR。例如，在順利完成傳輸要求時，這會設定為已傳輸的位元元組數目。驅動程式無法延伸此欄位。

傳回值

無

備註

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

針對讀取、寫入和 IOCTL 要求，驅動程式必須呼叫 WdfRequestCompleteWithInformation

針對非數據傳輸要求，請改為呼叫 WdfRequestComplete 是一個選項。

呼叫 WdfRequestCompleteWithInformation 相當於呼叫 WdfRequestSetInformation ，然後呼叫 WdfRequestComplete。

呼叫 WdfRequestCompleteWithInformation 之後，除非驅動程式呼叫 WdfObjectReference ，否則要求句柄已不再有效，以將一或多個額外的參考計數新增至要求物件。請注意， 在 WdfRequestCompleteWithInformation 傳回之後，驅動程式不得嘗試存取相關聯的 WDM IRP 結構，即使它已呼叫 WdfObjectReference 也一樣。

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

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

如需示範如何使用 WdfRequestCompleteWithInformation 擷取所複製位元組數目的程式碼範例，請參閱 VirtualSerial2 驅動程式範例。

範例

下列程式代碼範例示範 USB 裝置的驅動程式如何在 CompletionRoutine 回呼函式中呼叫 WdfRequestCompleteWithInformation。

VOID
EvtRequestReadCompletionRoutine(
    IN WDFREQUEST  Request,
    IN WDFIOTARGET  Target,
    PWDF_REQUEST_COMPLETION_PARAMS  CompletionParams,
    IN WDFCONTEXT  Context
    )
{    
    NTSTATUS  status;
    size_t  bytesRead = 0;
    PWDF_USB_REQUEST_COMPLETION_PARAMS  usbCompletionParams;

    UNREFERENCED_PARAMETER(Target);
    UNREFERENCED_PARAMETER(Context);

    status = CompletionParams->IoStatus.Status;
    usbCompletionParams = CompletionParams->Parameters.Usb.Completion;
    bytesRead =  usbCompletionParams->Parameters.PipeRead.Length;
 
    if (NT_SUCCESS(status)){
        TraceEvents(
                    TRACE_LEVEL_INFORMATION,
                    DBG_READ,
                    "Number of bytes read: %I64d\n",
                    (INT64)bytesRead
                    );
    } else {
        TraceEvents(
                    TRACE_LEVEL_ERROR,
                    DBG_READ,
                    "Read failed - request status 0x%x UsbdStatus 0x%x\n",
                    status,
                    usbCompletionParams->UsbdStatus
                    );
    }
    WdfRequestCompleteWithInformation(
                                      Request,
                                      status,
                                      bytesRead
                                      );
    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) 、 BufAfterReqReqCompletedIoctlA (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 ) 、 MdlAfterReqCompletedWrite) (、 MdlAfterReqCompletedWriteA (kmdf) 、 MemAfterReqCompletedIntIoctl (kmdf) ， MemAfterReqCompletedIntIoctlA (kmdf ) ， MemAfterReqCompletedIoctl () ， MemAfterReqCompletedIoctlA (kmdf) ， MemAfterReqCompletedRead (kmdf) 、 MemAfterReqCompletedReadA (kmdf) 、 MemAfterReqCompletedWrite (kmdf ) 、 MemAfterReqCompletedWriteA (kmdf) 、 NoCancelFromEvtSurpriseRemove (kmdf) 、 ReqDelete (kmdf) 、 ReqIsCancOnCancReq (kmdf ) 、 ReqNotCanceledLocal (kmdf ) 、 ReqSendFail (kmdf ) 、 RequestCompleted (kmdf ) 、 RequestCompletedLocal (kmdf)