共用方式為


WdfRequestStopAcknowledge 函式 (wdfrequest.h)

[適用於 KMDF 和 UMDF]

WdfRequestStopAcknowledge 方法會通知架構驅動程式已停止處理指定的 I/O 要求。

語法

void WdfRequestStopAcknowledge(
  [in] WDFREQUEST Request,
  [in] BOOLEAN    Requeue
);

參數

[in] Request

架構要求物件的句柄。

[in] Requeue

布爾值,如果為 TRUE,則會導致架構將要求重新排入佇列,讓架構再次將它傳遞給驅動程式。 如果 為 FALSE,則架構不會重新佇列要求。 如需詳細資訊,請參閱接下來的<備註>一節。

傳回值

備註

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

如果驅動程式註冊 I/O 佇列的 EvtIoStop 回呼函式,當佇列的基礎裝置離開其運作 (D0) 狀態時,架構會呼叫它。 架構會針對驅動程式尚未完成的每個 I/O 要求呼叫 EvtIoStop 回呼函式,包括驅動程式擁有的要求及其轉送至 I/O 目標的要求。 驅動程式必須執行下列其中一項,來完成、取消或延後處理每個要求:

  • 如果驅動程式擁有要求,它可以呼叫 WdfRequestComplete 來完成或取消要求。
  • 如果驅動程式已將要求轉送至 I/O 目標,它可以呼叫 WdfRequestCancelSentRequest 嘗試取消要求。
  • 如果驅動程式延後處理要求,則必須呼叫 WdfRequestStopAcknowledge
如果您的驅動程式呼叫 WdfRequestStopAcknowledge,則必須從其 EvtIoStop 回呼函式內呼叫此方法。

在驅動程式完成、取消或延遲 EvtIoStop 回呼函式接收的每個要求之前,架構不允許裝置離開其運作 (D0) 狀態。 這可能會讓系統無法進入其休眠狀態或另一個低系統電源狀態。

當驅動程式的 EvtIoStop 回呼函式呼叫 WdfRequestStopAcknowledge 時,可以將 Requeue 參數設定為 TRUEFALSE

  • [重新佇列 ] 設定為 TRUE 會導致架構將要求放回其 I/O 佇列。

    當基礎裝置回到其運作 (D0) 狀態時,架構會將要求重新傳遞給驅動程式。

  • [重新佇列 ] 設定為 FALSE 會導致架構無法重新佇列要求。 如果驅動程式 擁有 要求,則擁有權會與驅動程式一起保留。 如果驅動程式已轉送要求,驅動程式會負責在要求完成時處理要求。 驅動程式必須停止執行任何需要硬體存取的 I/O 處理。

    當基礎裝置回到其運作 (D0) 狀態時,架構會呼叫驅動程式的 EvtIoResume 回呼函式,讓驅動程式可以繼續處理要求。

如果驅動程式先前已呼叫 WdfRequestMarkCancelableWdfRequestMarkCancelableEx,它必須先呼叫 WdfRequestUnmarkCancelable ,再呼叫 WdfRequestStopAcknowledge ,並將 Requeue 設定為 TRUE

呼叫 WdfRequestStopAcknowledge 之前,驅動程式的 EvtIoStop 回呼函式必須停止所有需要存取基礎裝置的 I/O 要求處理,因為裝置即將進入低電源狀態。

如需 WdfRequestStopAcknowledge 方法的詳細資訊,請參閱 使用 Power-Managed I/O 佇列

範例

如果驅動程式呼叫 WdfRequestStopAcknowledge 並將 Requeue 設定為 TRUE,它之前必須呼叫 WdfRequestUnmarkCancelable

下列程式代碼範例是 EvtIoStop 回呼函式,會檢查接收的要求是否可取消,如果是,則會呼叫 WdfRequestUnmarkCancelable。 如果 WdfRequestUnmarkCancelable 傳回STATUS_CANCELLED,則範例只會傳回 ,因為驅動程式的 EvtRequestCancel 回呼函式會處理要求。 否則,此範例會呼叫 WdfRequestStopAcknowledge 並指定 TRUE ,讓架構在基礎裝置回到其運作 (D0) 狀態時重新佇列要求。

VOID
MyEvtIoStop(
    IN WDFQUEUE  Queue,
    IN WDFREQUEST  Request,
    IN ULONG  ActionFlags
    )
{
    NTSTATUS status;

    // TODO: Take steps here to suspend and, if necessary, roll back any processing that has already occurred on this request

    if (ActionFlags & WdfRequestStopRequestCancelable) {
        status = WdfRequestUnmarkCancelable(Request);
        if (status == STATUS_CANCELLED) {
            return;
        }
    }

    // Inform framework that driver is postponing processing, cause framework to redeliver request when device returns to D0

    WdfRequestStopAcknowledge(Request, TRUE);
}

一般而言,如果驅動程式呼叫 WdfRequestStopAcknowledge 並將 Requeue 設定為 FALSE,則會讓要求保持可取消。

下列程式代碼範例是 EvtIoStop 回呼函式,它會呼叫 WdfRequestStopAcknowledge 並指定 FALSE ,讓架構最終會呼叫驅動程式的 EvtIoResume 回呼函式,其中驅動程式會繼續處理要求。

如果可接受的程式代碼可以停止處理特定要求,並在稍後繼續,而不是重新傳遞要求並從頭重新啟動處理,您可以使用類似此程式碼的程序代碼。

VOID
MyEvtIoStop(
    IN WDFQUEUE  Queue,
    IN WDFREQUEST  Request,
    IN ULONG  ActionFlags
    )
{

    //TODO: Take steps here to suspend processing of the request so it can be resumed when power returns
	 
    // Acknowledge the stop, but leave the request under driver's ownership.
    // Provide a corresponding EvtIoResume handler to resume processing when power returns

    WdfRequestStopAcknowledge(Request, FALSE);
}

規格需求

需求
目標平台 Universal
最小 KMDF 版本 1.0
最低UMDF版本 2.0
標頭 wdfrequest.h (包含 Wdf.h)
程式庫 Wdf01000.sys (KMDF) ;WUDFx02000.dll (UMDF)
IRQL <=DISPATCH_LEVEL
DDI 合規性規則 DeferredRequestCompleted (kmdf) DriverCreate (kmdf ) , EvtIoStopCancel (kmdf) EvtIoStopCompleteOrStopAck (kmdf) EvtIoStopResume (kmdf) KmdfIrql (kmdf) KmdfIrql2 (kmdf ) 、KmdfIrqlExplicit (kmdf) 、 RequestCompleted (kmdf) RequestCompletedLocal (kmdf) StopAckWithinEvtIoStop (kmdf)

另請參閱

EvtIoStop

EvtRequestCancel

WdfRequestComplete