ハードウェア イベント

一部のオーディオ デバイスには、ハードウェア ボリューム コントロール ノブ、ミュート スイッチ、または他の種類の手動コントロールが用意されています。 アプリケーションは、ボリュームを調整するか、オーディオ ストリームの再生方法を変更することにより、これらのコントロールの変更に対応できます。 ユーザーがハードウェア コントロールを調整すると、ミニポート ドライバーは IPortEvents インターフェイスを使用して、ハードウェア イベントが発生したことをポート ドライバーに通知します。 つまり、ポート ドライバーは、デバイスから新しいコントロール設定を読み取ることができるようイベントのアプリケーションに通知します。

ミニポート ドライバーは、ポート ドライバーからの Init 呼び出し (IMiniportWavePci::Init など) を処理する時点で、IPortEvents インターフェイスのポート ドライバーを照会できます。 Microsoft Windows 98 SE、Windows Me、Windows 2000 以降では、そのクエリが成功します。 コード例については、以前のバージョンの Windows Driver Kit (WDK) の Sb16 サンプル オーディオ アダプターをご覧ください。

ポート ドライバーがドライバーの IMiniport::GetDescription メソッドを呼び出すと、デバイスがサポートするイベントなどを指定する PCFILTER_DESCRIPTOR 構造が出力されます。 イベントは、PCFILTER_DESCRIPTOR の Pins と Nodes のメンバーのオートメーション テーブルと、フィルター自体のオートメーション テーブルを指す AutomationTable メンバーで指定できます。 各イベントは、PCEVENT_ITEM 構造によって指定されます。 ドライバーは、PCEVENT_ITEM 構造の Set メンバーと Id メンバーを KSEVENTSETID_AudioControlChange および KSEVENT_CONTROL_CHANGE に設定し、ドライバーの EventHandler ルーチンへのポインターを Handler メンバーに読み込む必要があります。 ドライバーは、コントロール変更イベントの基本的なサポートを示すよう Flags メンバーの PCEVENT_ITEM_FLAG_BASICSUPPORT ビットを設定する必要があります。また、1 回の通知または定期的な通知をサポートすることを示す PCEVENT_ITEM_FLAG_ONESHOT ビットまたは PCEVENT_ITEM_FLAG_ENABLE ビットを設定する必要があります。

アプリケーションが後で mixerOpen 関数 (Microsoft Windows SDK ドキュメントで説明されています) を呼び出して特定のイベントの通知を要求すると、ポート ドライバーは、PCEVENT_REQUEST 構造へのポインターを使用してドライバーの EventHandler ルーチンを呼び出します。 この構造の Verb メンバーは PCEVENT_VERB_ADD に設定され、その EventItem メンバーは有効にするイベントを指定します。 PCEVENT_REQUEST 構造には、ドライバーが不透明なシステム データとして扱う必要がある KSEVENT_ENTRY 構造へのポインターも含まれています。 イベントを有効にした後、ハンドラーは同じ KSEVENT_ENTRY ポインターを使用して IPortEvents::AddEventToEventList を呼び出す必要があります。 この呼び出しにより、ハンドラーはイベントが有効になっていることを確認します。

ハードウェア イベントが発生し、ドライバーの割り込みサービス ルーチンがミュートまたはボリュームの変更を検出すると、ドライバーは IPortEvents::GenerateEventList を呼び出してイベントを説明するパラメーターのセットを使用して、ポート ドライバーにイベントを通知します。 たとえば、次の呼び出しでは、ライン出力ボリューム ノードのコントロールの変更について説明します。

    pPE->GenerateEventList(NULL, KSEVENT_CONTROL_CHANGE,
                           FALSE, ULONG(-1), TRUE, LINEOUT_VOL);

この呼び出し中、ポート ドライバーは、呼び出しパラメーターに一致するすべてのイベントのイベント一覧を検索し、これらのイベントを監視しているクライアントに通知を送信します。 この例では、pPE は IPortEvents オブジェクトへのポインターであり、LINEOUT_VOL はミニポート ドライバーがライン出力ボリューム ノードに割り当てるノード ID です。 指定されていないパラメーター (前の例のイベント セット GUID やピン ID など) はワイルドカードとして扱われ、常にリスト内の対応するパラメーターと一致します。