ACX 回線
このトピックでは、ACX 回線について説明します。 ACX の一般的な概要と ACX 用語の一覧については、「ACX オーディオ クラス拡張の概要」を参照してください。
「ACX オブジェクトの概要」で説明したように、AcxCircuit 回線は、ユーザーが認識するオーディオ デバイス (スピーカー、マイクなど) への部分的または完全なオーディオ パスを表します。 AcxCircuit には、少なくとも 1 つの入力ピンと 1 つの出力ピン (ACXPIN) があり、1 つ以上の AcxElements のようなオブジェクトを集約できます。 回線は、既存のエンドポイントとその機能を表します。
And ACX ストリームは、回線によって作成されたオーディオ ストリームを表すために作成されるドライバー コンポーネントです。 ストリームは、親回線の要素に基づいて作成された要素の一覧で構成されます。 ストリーム回線は、上位のユーザー モード ストリーミング サービスを直接操作するマルチスタック アーキテクチャ (部分的なオーディオ パス) 内の回線です。 コア回線は、オーディオ エンドポイント デバイスの ID を提供するマルチスタック アーキテクチャ (部分的なオーディオ パス) 内の回線です。
ACX 回線の識別
すべての ACX 回線には回線識別子があります。 ACX では以下を定義します。
名前 (str) は、この回線オーディオ デバイスの種類を一意に識別します。 INF の設定を見つけるために使用され、リモート デバイスからこの回路にアクセスするために使用されるシンボリック リンクの一部です。 例: "Render0"、"Render1"、または "Capture0"。
シンボリック リンク。 シンボリック リンクは、公開されているすべての回線に関連付けられます。 クライアントはこのシンボリック リンクを使用して、デバイス/回線との通信パスを開きます。
回線のコンポーネント ID (guid)。 回線インスタンス (ベンダー固有) を一意に識別します。 回線 URI が指定されている場合、AcxCircuitTemplate バインディングでは使用できません。
回線のコンポーネント URI (str)。 回線インスタンス (ベンダー固有) を一意に識別します。 回線 ID が指定されている場合、AcxCircuitTemplate バインディングでは使用できません。
回線ファクトリのコンポーネント ID (guid)。 回線ファクトリ インスタンス (ベンダー固有) を一意に識別します。 回線ファクトリ URI が指定されている場合、AcxCircuitTemplate バインディングでは使用できません。
回線ファクトリのコンポーネント URL (str)。 回線ファクトリ インスタンス (ベンダー固有) を一意に識別します。 回線ファクトリ ID が指定されている場合、AcxCircuitTemplate バインディングでは使用できません。
AcxCircuitCreate
AcxCircuitCreate 関数は、ACXCIRCUIT を作成するために使用されます。 AcxCircuitCreate 関数によって使用される不透明な ACXCIRCUIT_INIT 構造。 AcxCircuitInitAllocate は、ACXCIRCUIT_INIT 構造を初期化するために使用されます。
AcxFactoryCircuit
ACX ドライバーは、AcxFactoryCircuitCreate 関数と AcxDeviceAddFactoryCircuit 関数を使用して、電源投入シーケンス中に AcxFactoryCircuit オブジェクト (回線プロバイダー) を作成することもできます。
ACX マルチ回路組成
ACX は、完全なオーディオ パスを形成するまで回線をバインドします。 ACX では、オーディオ バインディングを使用してオーディオ回線を接続します。 詳しくは、「ACX マルチ回路組成」をご覧ください。
ACX 回線の動的な作成 (いつでも)
ACX は、必要に応じて動的回線を作成できます。 このため、ドライバーは、WdfPdoInitAllocate を呼び出して WDFDEVICE_INIT 構造体を割り当てます。 その後、ドライバーは、受信する PnP/電源コールバックを指定し、デバイスを作成します。 ドライバーは AcxDeviceAddCircuitDevice を呼び出すことで、新しいデバイス/回線をインスタンス化します。 詳細については、「ACX デバイスの列挙」を参照してください。
ACX 回線の動的な削除
ドライバーは、デバイスの一覧からオーディオ デバイスを削除するために、AcxDeviceRemoveCircuitDevice を呼び出します。 これにより、ACX 回線デバイス/回線エンティティの電源ダウン シーケンスがトリガーされます。 回線デバイス/回線は非同期的に削除されます。 詳細については、「ACX デバイスの列挙」を参照してください。
AcxDeviceRemoveCircuit と AcxDeviceDetachCircuit
回線終端を管理するには、一般的に 2 つの方法があります。 AcxDeviceDetachCircuit または AcxDeviceRemoveCircuit。
呼び出し元が AcxDeviceDetachCircuit を呼び出す場合は、AcxDeviceRemoveCircuit を呼び出してはなりません。 呼び出し元のドライバーが AcxDeviceDetachCircuit の後に回線を削除する場合は、WdfObjectDelete を使用します。
AcxDeviceRemoveCircuit を呼び出すことで、呼び出し元のドライバーは、この回線を削除し、デバイスから削除/削除するように ACX に指示します。 この場合、回線で WdfObjectDelete を呼び出す必要はありません。
要するに、AcxDeviceDetachCircuit は、ドライバーが回線オブジェクトの有効期間の管理を所有していることを意味し、AcxDeviceRemoveCircuit は回線が削除および削除されることを意味します。
WDF オブジェクトの有効期間の管理に関する一般的な情報については、「フレームワーク オブジェクトのライフサイクル」を参照してください。
AcxDeviceRemoveCircuitDevice
前述の回線終端とは異なり、AcxDeviceRemoveCircuitDevice はオーディオ ドライバーによって既存のオーディオ エンドポイントを削除するために使用され、ドライバーのライフサイクル中にいつでも呼び出すことができます。
ドライバーは、再調整時に常にオーディオ デバイスを破棄して再作成することもできます。 これは、デバイスが新しい設定が古いものと互換性がないことを検出した場合と同じシナリオです。
回線の削除は、EvtDevicePrepareHardware/EvtDeviceReleaseHardware コールバックで行う必要があり、新しい回線は EvtDevicePrepareHardwareで再作成されます。 ドライバーは、回線の登録を解除することによって回線を削除します (AcxDeviceRemoveCircuit を使用)。
EvtAcxCircuitReleaseHardware (EVT_ACX_CIRCUIT_RELEASE_HARDWARE) コールバック関数
ドライバーによって EvtAcxCircuitReleaseHardware コールバック関数が登録されている場合、フレームワークは次の遷移中にそれを呼び出します。
- リソースの再調整
- 順序正しい取り外し
- 突然の取り外し
ACX フレームワークは、WDF フレームワークがデバイスへの I/O 要求の送信を停止した後、デバイスに割り当てられている割り込みが無効化および切断され、デバイスがオフになった後、EvtAcxCircuitReleaseHardware コールバック関数を呼び出します。
ACX フレームワークは、WDF フレームワークがドライバーの EvtDeviceReleaseHardware コールバック関数を呼び出す前に、EvtAcxCircuitReleaseHardware コールバック関数を呼び出します。
フレームワークが EvtAcxCircuitReleaseHardware を呼び出しても、デバイスの PDO は引き続き存在し、電源オフ状態 (PCI 構成状態など) で使用可能なデバイス情報を照会できます。
加えて、フレームワークが EvtDeviceReleaseHardware に提供する変換されたハードウェア リソースは、引き続きデバイスに割り当てられます。 このコールバック関数の主な目的は、これらのリソースを解放し、特にドライバーの EvtAcxCircuitPrepareHardware コールバック関数がマッピングしたメモリ リソースのマップを解除することです。 ドライバーは、このコールバックを使用して、電源オフ状態で必要になる可能性があるその他の ACXCIRCUIT 管理アクティビティを実行することもできます。 通常、他のすべてのハードウェア シャットダウン操作は、ドライバーの EvtDeviceD0Exit コールバック関数で実行する必要があります。
ドライバーの EvtAcxCircuitPrepareHardware コールバック関数が呼び出された場合、EvtAcxCircuitPrepareHardware がエラー コードを返さない限り、ACX フレームワークは常にドライバーの EvtAcxCircuitReleaseHardware コールバック関数を呼び出します。
ハードウェア リソースについて詳しくは、「ハードウェア リソースの概要」をご覧ください。
EvtAcxFactoryCircuitReleaseHardware (EVT_ACX_FACTORY_CIRCUIT_RELEASE_HARDWARE) コールバック関数
フレームワークが EvtAcxFactoryCircuitReleaseHardware を呼び出しても、デバイスの PDO は引き続き存在し、電源オフ状態 (PCI 構成状態など) で使用可能なデバイス情報を照会できます。
加えて、フレームワークが EvtDeviceReleaseHardware に提供する変換されたハードウェア リソースは、引き続きデバイスに割り当てられます。 このコールバック関数の主な目的は、これらのリソースを解放し、特にドライバーの EvtAcxCircuitPrepareHardware コールバック関数がマッピングしたメモリ リソースのマップを解除することです。 ドライバーは、このコールバックを使用して、電源オフ状態で必要になる可能性があるその他の ACXCIRCUIT 管理アクティビティを実行することもできます。 通常、他のすべてのハードウェア シャットダウン操作は、ドライバーの EvtDeviceD0Exit コールバック関数で実行する必要があります。
ドライバーの EvtAcxFactoryCircuitPrepareHardware コールバック関数が呼び出された場合、EvtAcxFactoryCircuitPrepareHardware がエラー コードを返さない限り、ACX フレームワークは常にドライバーの EvtAcxFactoryCircuitReleaseHardware コールバック関数を呼び出します。
WDF と回線オブジェクトの管理の詳細については、「ACX WDF ドライバーの有効期間管理」を参照してください。