EVT_WDF_IO_QUEUE_IO_STOP回呼函式 (wdfio.h)

發行項
02/29/2024

[適用於 KMDF 和 UMDF]

驅動程式的 EvtIoStop 事件回呼函式會完成、重新佇列或暫停指定要求的處理，因為要求的 I/O 佇列已停止。

語法

EVT_WDF_IO_QUEUE_IO_STOP EvtWdfIoQueueIoStop;

void EvtWdfIoQueueIoStop(
  [in] WDFQUEUE Queue,
  [in] WDFREQUEST Request,
  [in] ULONG ActionFlags
)
{...}

參數

[in] Queue

與 I/O 要求相關聯的架構佇列物件的句柄。

[in] Request

架構要求物件的句柄。

[in] ActionFlags

一個或多個 WDF_REQUEST_STOP_ACTION_FLAGS型別旗標的位 OR，可識別呼叫回呼函式的原因，以及要求是否可取消。

傳回值

無

備註

驅動程式會在呼叫 WdfIoQueueCreate 時註冊 EvtIoStop 回呼函式。如需呼叫 WdfIoQueueCreate 的詳細資訊，請參閱建立 I/O 佇列。

如果驅動程式註冊 I/O 佇列的 EvtIoStop 回呼函式，當佇列的基礎裝置離開其運作 (D0) 狀態時，架構會呼叫它。架構會針對驅動程式尚未完成的每個 I/O 要求呼叫 EvtIoStop 回呼函式，包括驅動程式所擁有的要求，以及已轉送至 I/O 目標的要求。

在大部分情況下， EvtIoStop 回 呼函式會完成、取消或延後進一步處理 I/O 要求。

一般而言，驅動程式會執行下列其中一項：

如果驅動程式擁有 I/O 要求，它會呼叫 WdfRequestUnmarkCancelable (如果要求可取消) ，而且其中一個呼叫 WdfRequestStopAcknowledge 的 Requeue 值為 TRUE，或呼叫 WdfRequestComplete ，其完成狀態值為 STATUS_SUCCESS 或 STATUS_CANCELLED。
在可以安全地呼叫 WdfRequestXxx 方法之前，驅動程式必須確定其 EvtIoStop 的實作具有要求的獨佔存取權。

若要這樣做，驅動程式必須同步處理要求的存取權，以防止其他線程同時操作要求。您選擇的同步處理方法將取決於驅動程序的設計。

例如，如果要求保留在共用內容區域中， EvtIoStop 回呼可能會取得內部驅動程序鎖定、從共用內容中移除要求，然後釋放鎖定。此時， EvtIoStop 回 呼會擁有要求，而且可以安全地完成或重新排入要求佇列。

或者，驅動程式會延後進一步處理要求，並使用 Requeue 值為 FALSE 的 Requeue 值呼叫 WdfRequestStopAcknowledge。
如果驅動程式已將 I/O 要求轉送至 I/O 目標，它可以呼叫 WdfRequestCancelSentRequest 嘗試取消要求。
或者，如果驅動程式已將 I/O 要求轉送至自己的驅動程式堆棧中的較低層級驅動程式，且架構會使用 WdfRequestStopActionSuspend 的 ActionFlags 值呼叫驅動程式的 EvtIoStop 回呼，則驅動程式可以呼叫 WdfRequestStopAcknowledge，並以 FALSE 的 Requeue 值呼叫 WdfRequestStopAcknowledge。在這樣做之前，驅動程式應該先確認符合下列條件：
- 較低的驅動程式會停止處理所有未處理的 I/O 要求，以回應接收裝置集電源 IRP (Dx) 。
- 驅動程式的 CompletionRoutine 回呼函式可以在裝置處於低電量狀態時完成要求。

驅動程式可能會針對保證在少量時間內完成的要求，選擇在 EvtIoStop 中不採取任何動作。

在此情況下，架構會等到指定的要求完成，再將裝置 (或系統) 移至較低電源狀態或移除裝置。這種不動作可能會防止系統進入其休眠狀態或另一個低系統電源狀態。在極端情況下，可能會導致系統因錯誤檢查程式代碼 9F 而損毀。

如果在 ActionFlags 參數中設定 WdfRequestStopRequestCancelable 旗標，驅動程式必須先呼叫 WdfRequestUnmarkCancelable，才能呼叫 WdfRequestComplete 來完成 (或取消) 要求或 WdfRequestStopAcknowledge 重新佇列要求。

如果驅動程式從其中一個要求處理程式轉送 I/O 要求，並在要求的WDF_REQUEST_SEND_OPTIONS結構中指定WDF_REQUEST_SEND_OPTION_SEND_AND_FORGET旗標，架構就不會為此要求呼叫驅動程式的 EvtIoStop 回呼函式。不過，如果驅動程式從另一個線程轉送相同的 I/O 要求，架構可能會為此要求呼叫 EvtIoStop 。

如需 EvtIoStop 回 呼函式的詳細資訊，請參閱使用 Power-Managed I/O 佇列。

除非裝置或驅動程式WDF_OBJECT_ATTRIBUTES結構的 ExecutionLevel 成員設定為 WdfExecutionLevelPassive，否則可以在 IRQL <= DISPATCH_LEVEL 呼叫此回呼函式。