EVT_WDF_USB_READER_COMPLETION_ROUTINE コールバック関数 (wdfusb.h)

  • [アーティクル]

[KMDF と UMDF に適用]

ドライバーの EvtUsbTargetPipeReadComplete イベント コールバック関数は、継続的リーダーが正常に読み取り要求を完了したことをドライバーに通知します。

構文

EVT_WDF_USB_READER_COMPLETION_ROUTINE EvtWdfUsbReaderCompletionRoutine;

void EvtWdfUsbReaderCompletionRoutine(
  [in] WDFUSBPIPE Pipe,
  [in] WDFMEMORY Buffer,
  [in] size_t NumBytesTransferred,
  [in] WDFCONTEXT Context
)
{...}

パラメーター

[in] Pipe

フレームワーク パイプ オブジェクトへのハンドル。

[in] Buffer

デバイスからのデータを含むバッファーを表すフレームワーク メモリ オブジェクトへのハンドル。

[in] NumBytesTransferred

読み取りバッファー内にあるデータのバイト数。

[in] Context

パイプのWDF_USB_CONTINUOUS_READER_CONFIG構造体の EvtUsbTargetPipeReadCompleteContext メンバーでドライバーが指定したドライバー定義コンテキスト情報。

戻り値

なし

解説

EvtUsbTargetPipeReadComplete コールバック関数を登録するには、ドライバーは関数のアドレスをWDF_USB_CONTINUOUS_READER_CONFIG構造体に配置する必要があります。

ドライバーが USB パイプの連続リーダーを作成した場合、ドライバーの I/O ターゲットが正常に読み取り要求を完了するたびに、フレームワークはドライバーの EvtUsbTargetPipeReadComplete コールバック関数を呼び出します。 コールバック関数は、I/O ターゲットが読み取り要求を完了した IRQL で呼び出されます。これは通常、IRQL = DISPATCH_LEVELですが、DISPATCH_LEVEL以下です。 (I/O ターゲットが要求を正常に完了しない場合、フレームワークはドライバーの EvtUsbTargetPipeReadersFailed コールバック関数を呼び出します)。

デバイスから読み取られたデータを含むバッファーにアクセスするには、ドライバーは WdfMemoryGetBuffer を呼び出すことができます。 フレームワークは、WDF_USB_CONTINUOUS_READER_CONFIG構造体の HeaderLength メンバーによって定義されたヘッダーの後に、バッファーにデータを書き込みます。 WdfMemoryGetBuffer が返すポインターはヘッダーの先頭を指しますが、EvtUsbTargetPipeReadComplete コールバック関数の NumBytesTransferred パラメーターにはヘッダーの長さが含まれていないことに注意してください。

既定では、 フレームワークは、EvtUsbTargetPipeReadComplete コールバック関数が返した後、バッファーのメモリ オブジェクトを削除します。 ただし、コールバック関数が戻った後もメモリ オブジェクトを有効なままにしておく必要がある場合があります。 たとえば、ドライバーがコールバック関数から戻った後にメモリ オブジェクトの内容を処理できるように、フレームワーク パイプ オブジェクトのコンテキスト空間にオブジェクト ハンドルを格納する場合があります。 メモリ オブジェクトの有効期間を延長するには、コールバック関数がメモリ オブジェクトのハンドルを WdfObjectReference に渡す必要があります。 その後、フレームワークがオブジェクトを削除できるように、ドライバーは WdfObjectDereference を呼び出す必要があります。

フレームワークは、次の規則に従って 、EvtUsbTargetPipeReadComplete および EvtUsbTargetPipeReadersFailed コールバック関数の呼び出しを同期します。

  • これらのコールバック関数は、個々の USB パイプに対して同時に実行されません。
  • ドライバーが複数の USB パイプに対して複数の連続リーダーを作成し、複数 の EvtUsbTargetPipeReadComplete と EvtUsbTargetPipeReadersFailed コールバック関数を使用する場合、複数のコールバック関数を同時に実行できます。
  • ドライバーが既定の NumPendingReads 値または 1 より大きい値を指定しており、 EvtUsbTargetPipeReadComplete コールバック関数の実行中に読み取り要求が完了した場合、フレームワークはコールバック関数が返される前に EvtUsbTargetPipeReadComplete コールバック関数をもう一度呼び出すことができます。
  • フレームワークは、これらのコールバック関数を他のコールバック関数と同期しません。
WDF_USB_CONTINUOUS_READER_CONFIG構造体の BufferAttributes メンバーでは、ドライバーはメモリ オブジェクトの EvtCleanupCallback および EvtDestroyCallback コールバック関数を指定できます。 EvtCleanupCallback コールバック関数を指定した場合、EvtUsbTargetPipeReadComplete コールバック関数が戻った後、メモリ オブジェクトの削除を試みると、フレームワークはそのコールバック関数を呼び出します。 EvtUsbTargetPipeReadComplete コールバック関数が WdfObjectReference を呼び出した場合、EvtCleanupCallback コールバック関数 (指定されている場合) は WdfObjectDereference を呼び出さないでください。

ドライバーは、メモリ オブジェクトの使用が完了したら 、WdfObjectDereference を呼び出す必要があります。 フレームワークは、ドライバーの EvtDestroyCallback コールバック関数 (指定されている場合) を呼び出し、メモリ オブジェクトを削除できます。

EvtUsbTargetPipeReadComplete コールバック関数と USB I/O ターゲットの詳細については、「USB I/O ターゲット」を参照してください。

要件

要件 値
対象プラットフォーム ユニバーサル
最小 KMDF バージョン 1.0
最小 UMDF バージョン 2.0
Header wdfusb.h (Wdf.h を含む)
IRQL <=DISPATCH_LEVEL (「解説」セクションを参照)。

こちらもご覧ください

EvtUsbTargetPipeReadersFailed

WDF_USB_CONTINUOUS_READER_CONFIG

WdfMemoryGetBuffer