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 コールバック関数をもう一度呼び出すことができます。
- フレームワークは、これらのコールバック関数を他のコールバック関数と同期しません。
ドライバーは、メモリ オブジェクトの使用が完了したら 、WdfObjectDereference を呼び出す必要があります。 フレームワークは、ドライバーの EvtDestroyCallback コールバック関数 (指定されている場合) を呼び出し、メモリ オブジェクトを削除できます。
EvtUsbTargetPipeReadComplete コールバック関数と USB I/O ターゲットの詳細については、「USB I/O ターゲット」を参照してください。
要件
| 要件 | 値 |
|---|---|
| 対象プラットフォーム | ユニバーサル |
| 最小 KMDF バージョン | 1.0 |
| 最小 UMDF バージョン | 2.0 |
| Header | wdfusb.h (Wdf.h を含む) |
| IRQL | <=DISPATCH_LEVEL (「解説」セクションを参照)。 |