EVT_WDF_IO_QUEUE_IO_CANCELED_ON_QUEUE回呼函式 (wdfio.h)

[適用于 KMDF 和 UMDF]

驅動程式的 EvtIoCanceledOnQueue 事件回呼函式會通知驅動程式它必須完成架構已從 I/O 佇列中移除的 I/O 要求。

語法

EVT_WDF_IO_QUEUE_IO_CANCELED_ON_QUEUE EvtWdfIoQueueIoCanceledOnQueue;

void EvtWdfIoQueueIoCanceledOnQueue(
  [in] WDFQUEUE Queue,
  [in] WDFREQUEST Request
)
{...}

參數

[in] Queue

I/O 佇列物件的控制碼。

[in] Request

要求物件的控制碼。

傳回值

備註

當驅動程式呼叫WdfIoQueueCreate方法時,會註冊EvtIoCanceledOnQueue回呼函式。 如需呼叫 WdfIoQueueCreate的詳細資訊,請參閱 建立 I/O 佇列

如果驅動程式註冊 I/O 佇列的 EvtIoCanceledOnQueue 回呼函式,架構會在下列情況下呼叫回呼函式:

在架構呼叫EvtIoCanceledOnQueue回呼函式之後,驅動程式會擁有要求物件,而且必須在EvtIoCanceledOnQueue或更新版本中以適當的狀態碼完成要求。 當架構呼叫 EvtIoCanceledOnQueue時,要求仍與 I/O 佇列相關聯,但驅動程式無法重新佇列要求。 即使驅動程式未在 EvtIoCanceledOnQueue中完成要求,要求的擁有權仍會與驅動程式保持一致。 如果驅動程式在 EvtIoCanceledOnQueue 傳回之後完成要求,它就無法呼叫 WdfIoQueueFindRequestWdfIoQueueRetrieveFoundRequest 來重新取得要求的擁有權,因為驅動程式已經有要求的擁有權。

一般而言,在 EvtIoCanceledOnQueue中,驅動程式 會完成 I/O 要求 ,且完成狀態為 STATUS_CANCELLED。

在某些情況下,驅動程式可能先前已將 I/O 要求重新佇列至手動佇列,或許可以等候資訊。 例如,在其其中一個 要求處理常式中,驅動程式可能會放置與手動佇列中擱置 DMA 交易相關聯的 I/O 要求。 在此情況下,驅動程式會嘗試在其EvtIoCanceledOnQueue回呼中取消 DMA 交易。 根據取消作業的結果,驅動程式會在 EvtIoCanceledOnQueue 或更新版本中完成具有適當狀態的要求。

架構不會針對架構從未傳遞至驅動程式的 I/O 要求呼叫驅動程式的 EvtIoCanceledOnQueue 回呼函式。

架構會在判斷 I/O 要求已取消時立即呼叫 EvtIoCanceledOnQueue 回呼函式,不論驅動程式針對 I/O 佇列所設定的 分派方法 為何。 因此,架構可以針對下列專案呼叫 EvtIoCanceledOnQueue 回呼函式:

  • 佇列中使用 循序分派的要求,即使驅動程式目前擁有來自佇列的另一個要求也一樣。
  • 驅動程式在佇列中設定 NumberOfPresentedRequests的要求,即使驅動程式目前擁有要求數目上限也一樣。
如需 EvtIoCanceledOnQueue 回呼函式的詳細資訊,請參閱 取消 I/O 要求

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

如果 IRQL PASSIVE_LEVEL,架構會呼叫 重要區域內的回呼函式。

範例

若要定義 EvtIoCanceledOnQueue 回呼函式,您必須先提供函式宣告,以識別您要定義的回呼函式類型。 Windows 提供一組驅動程式的回呼函式類型。 使用回呼函式類型宣告函式有助於 驅動程式的程式碼分析靜態驅動程式驗證器 (SDV) ,以及其他驗證工具會尋找錯誤,而且這是撰寫 Windows 作業系統驅動程式的需求。

若要定義 EvtIoCanceledOnQueue 回呼函式,您必須先提供 SDV 和其他驗證工具所需的函式宣告。 下列範例取自 PCMCIA 智慧卡驅動程式 範例。

EVT_WDF_IO_QUEUE_IO_CANCELED_ON_QUEUE PscrEvtIoCanceledOnQueue;

PCMCIA 智慧卡驅動程式 範例中,驅動程式會使用手動佇列來儲存擱置的智慧卡通知要求。 驅動程式會提供 EvtIoCanceledOnQueue 回呼函式,讓驅動程式清除通知欄位並完成要求。

_Use_decl_annotations_
VOID
PscrEvtIoCanceledOnQueue(
    WDFQUEUE  Queue,
    WDFREQUEST  Request
    )

{
    PDEVICE_EXTENSION DeviceExtension;
    PSMARTCARD_EXTENSION smartcardExtension;

    DeviceExtension = GetDeviceExtension(WdfIoQueueGetDevice(Queue));
    smartcardExtension = (PSMARTCARD_EXTENSION) &DeviceExtension->SmartcardExtension;

    //KdPrint(("Cancelled on queue 0x%x\n", WdfRequestWdmGetIrp(Request)));

    InterlockedExchangePointer(
                             &(smartcardExtension->OsData->NotificationIrp),
                             NULL
                             );

    WdfRequestComplete(Request, STATUS_CANCELLED);
}

EVT_WDF_IO_QUEUE_IO_CANCELED_ON_QUEUE函式類型定義于 Wdfio.h 標頭檔中。 若要在執行程式碼分析工具時更精確地識別錯誤,請務必將 Use_decl_annotations 注釋新增至函式定義。 Use_decl_annotations注釋可確保使用標頭檔中套用至EVT_WDF_IO_QUEUE_IO_CANCELED_ON_QUEUE函式類型的批註。 如需函數宣告需求的詳細資訊,請參閱 使用 KMDF 驅動程式的函式角色類型來宣告函式。 如需 Use_decl_annotations的詳細資訊,請參閱 標注函式行為

規格需求

   
目標平臺 環球
最小 KMDF 版本 1.0
最低 UMDF 版本 2.0
標頭 wdfio.h (包含 Wdf.h)
IRQL <= DISPATCH_LEVEL (請參閱一節)

另請參閱

WdfIoQueueCreate

WdfRequestForwardToIoQueue