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 傳回之後完成要求，它就無法呼叫 WdfIoQueueFindRequest 和 WdfIoQueueRetrieveFoundRequest 來重新取得要求的擁有權，因為驅動程式已經有要求的擁有權。

一般而言，在 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的詳細資訊，請參閱 標註函式行為。

規格需求

需求 值
目標平台 Universal
最低 KMDF 版本 1.0
最低UMDF版本 2.0
標頭 wdfio.h (包含 Wdf.h)
IRQL <= DISPATCH_LEVEL (请参阅一节)

另請參閱

WdfIoQueueCreate

WdfRequestForwardToIoQueue