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 コールバック関数を登録する場合、フレームワークは次の状況でコールバック関数を呼び出します。

  • 要求ハンドラーは I/O キューから I/O 要求を受信し、ドライバーは WdfRequestForwardToIoQueue、WdfRequestForwardToParentDeviceIoQueue、または WdfRequestRequeue を呼び出して、EvtIoCanceledOnQueue コールバック関数が登録されている I/O キューに要求を再要求し、関連付けられた I/O 操作が取り消されます。
  • ドライバーの EvtIoInCallerContext コールバック関数は I/O 要求を受け取り、ドライバーは WdfDeviceEnqueueRequest を呼び出してフレームワークに要求を渡し、フレームワークは EvtIoCanceledOnQueue コールバック関数が登録されている I/O キューに要求を配置し、関連付けられた I/O 操作が後で取り消されます。
フレームワークが EvtIoCanceledOnQueue コールバック関数を呼び出した後、ドライバーは要求オブジェクトを所有し、EvtIoCanceledOnQueue 以降のいずれかの適切な状態コードで要求を完了する必要があります。 フレームワークが EvtIoCanceledOnQueue を呼び出すと、要求は引き続き I/O キューに関連付けられますが、ドライバーは要求を再要求できません。 ドライバーが EvtIoCanceledOnQueue で要求を完了していない場合でも、要求の所有権はドライバーと共に維持されます。 EvtIoCanceledOnQueue が返された後にドライバーが要求を完了した場合、ドライバーは要求の所有権を既に持っているため、WdfIoQueueFindRequest と WdfIoQueueRetrieveFoundRequest を呼び出して要求の所有権を再取得することはできません。

通常、 EvtIoCanceledOnQueue では、ドライバーは完了状態が STATUS_CANCELLED で I/O 要求を完了 します。

場合によっては、ドライバーが以前に手動キューに I/O 要求を再キューに入れたことがあります。おそらく、情報を待つ必要があります。 たとえば、その 要求ハンドラーの 1 つでは、ドライバーが手動キューに保留中の DMA トランザクションに関連付けられている I/O 要求を配置する場合があります。 この場合、ドライバーは EvtIoCanceledOnQueue コールバックで DMA トランザクションを取り消そうとします。 ドライバーは、取り消し操作の結果に応じて、 EvtIoCanceledOnQueue 以降のいずれかの適切な状態で要求を完了します。

フレームワークは、フレームワークがドライバーに配信したことがない I/O 要求に対して、ドライバーの EvtIoCanceledOnQueue コールバック関数を呼び出しません。

フレームワークは、ドライバーが I/O キューに設定したディスパッチ メソッドに関係なく、I/O 要求が取り消されたと判断するとすぐに EvtIoCanceledOnQueue コールバック関数を呼び出します。 そのため、フレームワークは、 次の場合に EvtIoCanceledOnQueue コールバック関数を呼び出すことができます。

EvtIoCanceledOnQueue コールバック関数の詳細については、「I/O 要求の取り消し」を参照してください。

EvtIoCanceledOnQueue コールバック関数は、デバイスまたはドライバーのWDF_OBJECT_ATTRIBUTES構造体の ExecutionLevel メンバーが WdfExecutionLevelPassive に設定されていない限り、IRQL <= DISPATCH_LEVELで呼び出すことができます。

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
Header wdfio.h (Wdf.h を含む)
IRQL <= DISPATCH_LEVEL (「解説」セクションを参照)

こちらもご覧ください

WdfIoQueueCreate

WdfRequestForwardToIoQueue