作業項目の使用
警告
UMDF 2 は UMDF の最新バージョンであり、UMDF 1 よりも優先されます。 すべての新しい UMDF ドライバーは、UMDF 2 を使用して記述する必要があります。 UMDF 1 には新機能が追加されておらず、Windows 10 の新しいバージョンでは UMDF 1 のサポートが制限されています。 ユニバーサル Windows ドライバーでは、UMDF 2 を使用する必要があります。
アーカイブされた UMDF 1 サンプルは、「Windows 11, バージョン 22H2 - 2022 年 5 月 ドライバーサンプルの更新」でご確認いただけます。
詳しくは、「UMDF の概要」をご覧ください。
作業項目は、ドライバーが OnWorkItem イベント コールバック関数で実行するタスクです。 これらの関数は非同期的に実行されます。
UMDF ドライバーは、割り込みラインが複数のデバイスで共有される可能性があるため、割り込みサービス要求 (ISR) の実行を遅延させることなく、OnInterruptIsr が追加処理を実行する必要がある場合に、一般的に作業項目を使用します。
通常、ドライバーの OnInterruptIsr コールバック関数は、作業項目オブジェクトを作成し、システムの作業項目キューに追加します。 その後、スレッド プール スレッドはオブジェクトをデキューし、作業項目の OnWorkItem コールバック関数を呼び出します。
作業項目のセットアップ
作業項目のセットアップには、ドライバーで次の操作を行う必要があります。
作業項目を作成する。
ドライバーは IWDFDevice3::CreateWorkItem を呼び出して作業項目オブジェクトを作成し、作業項目を処理する OnWorkItem コールバック関数を識別します。
作業項目に関する情報を格納します。
通常、ドライバーは、作業項目オブジェクトのコンテキスト メモリを使用して、OnWorkItem コールバック関数が実行する必要があるタスクに関する情報を格納します。 OnWorkItem コールバック関数が呼び出されると、このコンテキスト メモリにアクセスして情報を取得できます。 コンテキスト メモリの割り当て方法とアクセス方法については、IWDFObject::AssignContextをご参照ください。
作業項目をシステムの作業項目キューに追加します。
ドライバーは IWDFWorkItem::Enqueue を呼び出します。これによって、ドライバーの作業項目が作業項目キューに追加されます。
ドライバーが IWDFDevice3::CreateWorkItem を呼び出すときに、必要に応じて親オブジェクト (デバイス オブジェクトやキュー オブジェクトなど) を指定できます。 そのオブジェクトが削除されると、そのオブジェクトに関連付けられている既存の作業項目も削除されます。
WorkItem コールバック関数の使用
作業項目キューに作業項目が追加されると、システム ワーカー スレッドが使用可能になるまでキューに再メインされます。 システム ワーカー スレッドは、キューから作業項目を削除し、ドライバーの OnWorkItem コールバック関数を呼び出し、作業項目オブジェクトを入力として渡します。
通常、OnWorkItem コールバック関数は次の手順を実行します。
- 作業項目オブジェクトのコンテキスト メモリにアクセスして、作業項目に関するドライバー指定の情報を取得します。
- 指定したタスクを実行します。 必要に応じて、作業項目の親オブジェクトを決定するために、コールバック関数は IWDFWorkItem::GetParentObject を呼び出すことができます。
- ドライバーが作業項目を再キューに入れ替える場合は、作業項目のハンドルを再利用できるようになったことを示します。
いくつかのドライバーは、作業項目キューから作業項目をフラッシュするために IWDFWorkItem::Flush を呼び出す必要がある場合があります。 ドライバーが Flush メソッドを呼び出した場合、ワーカー スレッドが指定した作業項目を作業項目キューから削除し、ドライバーの OnWorkItem コールバック関数を呼び出すまで、メソッドは戻りません。その後、作業項目の処理後に OnWorkItem コールバック関数が返されます。