次の方法で共有

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

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

戻り値

何一つ

備考

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 コールバック関数を再度呼び出すことができます。
  • フレームワークは、これらのコールバック関数を他のコールバック関数と同期しません。
BufferAttributesWDF_USB_CONTINUOUS_READER_CONFIG 構造体のメンバーで、ドライバーは EvtCleanupCallback 指定し、メモリ オブジェクトのコールバック関数 EvtDestroyCallback を できます。 EvtCleanupCallback コールバック関数を指定した場合、フレームワークはメモリ オブジェクトの削除を試みたときに、そのコールバック関数 EvtUsbTargetPipeReadComplete コールバック関数が返された後に呼び出します。 EvtUsbTargetPipeReadComplete コールバック関数が WdfObjectReference 呼び出した場合、EvtCleanupCallback コールバック関数 (指定されている場合) は、WdfObjectDereference 呼び出してはなりません。

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

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

必要条件

要件 価値
ターゲット プラットフォーム の 万国
最小 KMDF バージョン 1.0
UMDF の最小バージョン を する 2.0
ヘッダー wdfusb.h (Wdf.h を含む)
IRQL <=DISPATCH_LEVEL (「解説」セクションを参照)。

関連項目

EvtUsbTargetPipeReadersFailed の

WDF_USB_CONTINUOUS_READER_CONFIG

WdfMemoryGetBuffer の