ACX 回線

[アーティクル]
03/12/2024

このトピックでは、ACX 回線について説明します。 ACX の一般的な概要と ACX 用語の一覧については、ACX オーディオクラス拡張機能の概要を参照してください。

ACX オブジェクトの概要で説明されているように、AcxCircuit オブジェクトは、ユーザーが認識するオーディオデバイス (スピーカー、マイクなど) への部分的または完全なオーディオパスを表します。 AcxCircuit には、少なくとも 1 つの入力ピンと 1 つの出力ピン (ACXPIN) があり、オブジェクトのような 1 つ以上の AcxElement を集約できます。回線は、既存のエンドポイントとその機能を表します。

ACX Stream は、回線によって作成されたオーディオストリームを表すために作成されたドライバーコンポーネントです。 Stream は、親回線の要素に基づいて作成された要素の一覧で構成されます。 ストリーム回線は、上位のユーザーモードストリーミングサービスと直接インターフェイスする、マルチスタックアーキテクチャ (部分的なオーディオパス) の回線です。 コア回線は、オーディオエンドポイントデバイスの ID を提供するマルチスタックアーキテクチャ (部分的なオーディオパス) の回線です。

Note

ACX ヘッダーとライブラリは、WDK 10.0.22621.2428 (2023 年 10 月 24 日リリース) には含まれていませんが、以前のバージョンと WDK の最新 (25000 シリーズビルド) Insider Preview で使用できます。 WDK のプレビューバージョンの詳細については、「Windows Driver Kit (WDK) のプレビューバージョンのインストール」を参照してください。

ACX 回線の識別

すべての ACX 回線には回線識別子があります。 ACX では、次の定義が行われます。

名前 (str)、この回線オーディオデバイスの種類を一意に識別します。 INF の設定を見つけるために使用され、リモートデバイスからこの回線にアクセスするために使用されるシンボリックリンクの一部です。例: "Render0"、"Render1"、または "Capture0"。
シンボリックリンク。シンボリックリンクは、公開されているすべての回線に関連付けられます。クライアントはこのシンボリックリンクを使用して、デバイス/回線との通信パスを開きます。
回線のコンポーネント ID (guid)。 回線インスタンス (ベンダー固有) を一意に識別します。回線 URI が指定されている場合、AcxCircuitTemplate バインディングでは使用できません。
回線のコンポーネント URI (str)。 回線インスタンス (ベンダー固有) を一意に識別します。回線 ID が指定されている場合、AcxCircuitTemplate バインディングでは使用できません。
Circuit Factory のコンポーネント ID (guid)。 回線ファクトリインスタンス (ベンダー固有) を一意に識別します。回線ファクトリ URI が指定されている場合、AcxCircuitTemplate バインドでは使用できません。
回線ファクトリのコンポーネント URI (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_RELEA Standard Edition_HARDWARE) コールバック関数

ドライバーが EvtAcxCircuitReleaseHardware コールバック関数を登録している場合、フレームワークは次の遷移中にそれを呼び出します。

リソースの再調整
Orderly の削除
突然の削除

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_RELEA Standard Edition_HARDWARE) コールバック関数

フレームワークが EvtAcxFactoryCircuitReleaseHardware を呼び出すと、デバイスの PDO は引き続き存在し、電源オフ状態 (PCI 構成状態など) で使用可能なデバイス情報を照会できます。

EvtAcxFactoryCircuitPrepareHardware がエラーコードを返さない限り、ドライバーの EvtAcxFactoryCircuitPrepareHardware コールバック関数が呼び出された場合、ACX フレームワークは常にドライバーの EvtAcxFactoryCircuitReleaseHardware コールバック関数を呼び出します。

WDF および回線オブジェクトの管理の詳細については、ACX WDF ドライバーの有効期間管理を参照してください。

次の方法で共有