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 參數設定為 TRUE 或 FALSE：

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

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

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

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

如果驅動程式先前已呼叫 WdfRequestMarkCancelable 或 WdfRequestMarkCancelableEx，它必須先呼叫 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