Microsoft Windows Driver Model (WDM) オーディオ ドライバーは、オーディオ デバイスを KS フィルターとして表し、デバイス上のハードウェア バッファーをフィルターのピンとして表します。 クライアントがこれらのフィルターまたはピン オブジェクトのいずれかにプロパティ要求を送信すると、ポート ドライバーは要求を受け取り、ポート ドライバーまたはミニポート ドライバーの適切なプロパティ ハンドラーに要求をルーティングします。
オーディオ デバイスでは、次の 3 種類のプロパティがサポートされています。
フィルター プロパティ
フィルター プロパティは、フィルター内の特定のピンまたはノードのプロパティではなく、フィルター全体のプロパティです。 フィルター プロパティの要求はフィルター ハンドルを指定しますが、ノード ID は指定しません。
ピン プロパティ
pin プロパティは、フィルター上の特定のピン インスタンスのプロパティです。 これらのプロパティの要求では、ピン ハンドルを指定しますが、ノード ID は指定しません。
ノードのプロパティ
ノード プロパティは、フィルター内のトポロジ ノードのプロパティです。 ノード プロパティの要求では、フィルター ハンドルまたはピン ハンドルとノード ID を指定します。
ノード プロパティ要求でフィルター ハンドルまたはピン ハンドルを指定するかどうかは、ノードがフィルターに対して一意かどうかによって異なります。 詳細については、次の「ノードのプロパティ」セクションを参照してください。
次の図は、次の 3 種類のプロパティ要求を示しています。ピン インスタンスに送信される pin プロパティ要求、ノードに送信されたノード プロパティ要求 (フィルターまたはピン インスタンス上)、フィルター インスタンスに送信されるフィルター プロパティ要求です。
通常、ポート ドライバーは、フィルターとピンのプロパティのほとんどの要求を処理し、ミニポート ドライバーは、ノードのプロパティの要求を処理します。
ポート ドライバーには、 SysAudio システム ドライバー ( KSPROPSETID_Sysaudio と KSPROPSETID_Sysaudio_Pinを参照) および WDMAud システム ドライバーで使用されるフィルターとピンのプロパティに独自の組み込みハンドラーが用意されています。 ミニポート ドライバーは、ポート ドライバーが処理するプロパティのハンドラーを実装する必要はありません。 一般的なミニポートドライバーは、フィルターとピンのプロパティのためのハンドラーをほとんど提供しません。 ミニポート ドライバーは、オーディオ デバイスのハードウェアに依存する機能を表すノードのプロパティのハンドラーを提供します。 ポート ドライバーは、 KSPROPERTY_TOPOLOGY_NAMEを除き、ノード プロパティの組み込み処理を提供しません。
ポート ドライバーとミニポート ドライバーの両方が同じプロパティのハンドラーを提供する場合、ポート ドライバーは独自のハンドラーを使用し、ミニポート ドライバーのハンドラーを無視します。
フィルター記述子
ポート ドライバーは、 IMiniport::GetDescription メソッドを呼び出すことによって、ミニポート ドライバーのプロパティ ハンドラーへのポインターを取得します。 このメソッドを使用して、ポート ドライバーは、ミニポート ドライバーのフィルター記述子へのポインターを取得します。これは、 PCFILTER_DESCRIPTOR型の構造体です。 この構造体は、フィルター、ピン、およびノードのプロパティのミニポート ドライバーのプロパティ ハンドラーを指定します。
PCFILTER_DESCRIPTOR構造体の AutomationTable メンバーは、フィルターのオートメーション テーブルを指します。 次の表は、フィルター プロパティのミニポート ドライバーのプロパティ ハンドラーを指定します。
PCFILTER_DESCRIPTOR構造体の Pins メンバーには、 ピン のオートメーション テーブルが含まれています。 各テーブルは、特定のピンの種類のピン プロパティのプロパティ ハンドラーを指定します。
PCFILTER_DESCRIPTOR構造体の Nodes メンバーには、フィルター内のトポロジ ノードのオートメーション テーブルが含まれています。 各テーブルは、特定のノード 型のノード プロパティのプロパティ ハンドラーを指定します。
フィルターのプロパティ
ポート ドライバーは、PCFILTER_DESCRIPTORの AutomationTable メンバーを介してミニポート ドライバーのフィルター プロパティ ハンドラーにアクセスします。 通常、このオートメーション テーブルにはいくつかのハンドラーが含まれています。ポート ドライバーには、SysAudio と WDMAud がオーディオ デバイスのクエリと構成に使用するすべてのフィルター プロパティに独自の組み込みハンドラーが用意されているためです。
ただし、ミニポート ドライバーは、ポート ドライバーで使用できないハードウェアに依存する情報 を提供するKSPROPERTY_GENERAL_COMPONENTID などのフィルター プロパティのハンドラーを提供できます。 Microsoft Windows Driver Kit (WDK) の 2 つのサンプル オーディオ ドライバーが、KSPROPERTY_GENERAL_COMPONENTID プロパティを処理します。 詳細については、「 サンプル オーディオ ドライバー」で説明されている Sysvad サンプル ドライバーのミニポート ドライバーの実装を参照してください。
Portcls.sys のすべてのポート ドライバーは、 KSPROPSETID_PinおよびKSPROPSETID_Topology プロパティ セットの処理 を 提供します。 これらのセット内のすべてのプロパティはフィルター プロパティです。 ただし、ノード プロパティである KSPROPERTY_TOPOLOGY_NAME を除きます (要求のターゲットを指定するために、ピン ハンドルではなくフィルター ハンドルを使用します)。 ポート ドライバーは、KSPROPSETID_Pin プロパティの次のサブセットをサポートしています。
KSPROPERTY_PIN_CONSTRAINEDDATARANGES
KSPROPERTY_PIN_DATAINTERSECTION
KSPROPERTY_PIN_GLOBALCINSTANCES
KSPROPERTY_PIN_NECESSARYINSTANCES
KSPROPERTY_PIN_PHYSICALCONNECTION
KSPROPERTY_PIN_PROPOSEDATAFORMAT
KSPROPERTY_PIN_PROPOSEDATAFORMAT2
これらのプロパティは、フィルターに属するピン ファクトリに関する情報を提供します。 通常、クライアントは、ピン インスタンスを作成する前に、これらのプロパティのフィルターに対してクエリを実行します。 ポート ドライバーは、フィルターの内部トポロジに関する情報を提供する 4 つの KSPROPSETID_Topology プロパティをすべてサポートします。
さらに、DMus ポート ドライバーは、DirectMusic フィルターの取得専用プロパティである KSPROPERTY_SYNTH_MASTERCLOCK プロパティのハンドラーを提供します。 KSPROPERTY_SYNTH_MASTERCLOCKは、 KSPROPSETID_SynthClock プロパティ セットのメンバーです。
ピンのプロパティ
ポートドライバーは、PCFILTER_DESCRIPTOR の ピン メンバーを通じて、ミニポートドライバーのピンプロパティハンドラーにアクセスします。 このメンバーはピン記述子の配列を指し、各記述子はピン型のオートメーション テーブルを指します (ピン ID で識別されます。これは単に配列インデックスです)。
通常、これらのオートメーションテーブルにはほとんどエントリが含まれていません。これは、ポートドライバーがSysAudioとWDMAudで使用されるすべてのピンプロパティに対して独自のハンドラーを提供しているためです。 ミニポート ドライバーには、ポート ドライバーが処理しない 1 つ以上の pin プロパティのハンドラーを提供するオプションがありますが、これらのプロパティを知っているクライアントのみが、それらのプロパティ要求を送信できます。
トポロジ ポート ドライバーを除き、Portcls.sys のすべてのポート ドライバーは、次のピン プロパティの組み込みハンドラーを提供します。
KSPROPERTY_CONNECTION_DATAFORMAT
KSPROPERTY_CONNECTION_ALLOCATORFRAMING
KSPROPERTY_DRMAUDIOSTREAM_CONTENTID
この一覧のプロパティの一部には、ミニポート ドライバーからのハードウェアに依存する情報が必要です。 ポート ドライバーは、これらのプロパティのいずれかの要求を含む IRP を受信すると、ミニポート ドライバーに IRP を渡しません。 代わりに、ポート ドライバーは要求自体を処理しますが、そのハンドラーは、ミニポート ドライバーのエントリ ポイントを呼び出すことによって必要な情報を取得します。 たとえば、ポート ドライバーは、KSPROPERTY_AUDIO_POSITION要求に対して独自のプロパティ ハンドラーを提供します。 このハンドラーは、ミニポート ドライバー ストリームの GetPosition メソッド ( IMiniportWavePciStream::GetPosition など) を呼び出して現在の位置を取得するだけです。
ノードのプロパティ
ポート ドライバーは、ミニポート ドライバーのノード プロパティ ハンドラーにPCFILTER_DESCRIPTORの ノード メンバーを介してアクセスします。 このメンバーはノード記述子の配列を指し、各記述子はノード型のオートメーション テーブルを指します (単に配列インデックスであるノード ID で識別されます)。 通常、ミニポート ドライバーに属するプロパティ ハンドラーのすべてまたはほとんどの ノード 配列に存在します。 オーディオ ドライバーは、オーディオ デバイス内のハードウェア コントロールをトポロジ ノードとして表し、プロパティ メカニズムを使用して、クライアントにハードウェア依存の制御設定へのアクセスを提供します。
前述のように、クライアントはフィルター プロパティ要求をフィルター ハンドルに送信し、pin プロパティ要求をピン ハンドルに送信します。 フィルターまたはピン のインスタンスとは異なり、ノードはカーネル オブジェクトではなく、ハンドルを持っていません。 クライアントは、ノード プロパティ要求をピン ハンドルまたはフィルター ハンドルに送信しますが、要求は、要求がピンまたはフィルター プロパティではなくノード プロパティ用であることを示すノード ID も指定します。
ノード プロパティがフィルター ハンドルまたはピン ハンドルを使用する必要があるかどうかを判断するための一般的な規則を次に示します。
フィルターに特定のピンの種類のインスタンスが複数含まれており、その種類の各ピンに特定のノード ID を持つノードが含まれている場合、各ピン インスタンスにはノードのインスタンスが含まれます。 この場合、ノード プロパティ要求では、同じノード タイプの複数のインスタンスを区別するために、(フィルター ハンドルではなく) ピン ハンドルを指定する必要があります。 ピン ハンドルとノード ID の組み合わせによって、特定のノード インスタンスが要求のターゲットとして明確に識別されます。
フィルターに特定のノードのインスタンスが 1 つだけ含まれている場合、ノード プロパティ要求はフィルター ハンドルを指定します。 フィルター ハンドルとノード ID の組み合わせは、要求のターゲットであるノードを明確に識別するのに十分です。
ただし、特定のノード プロパティのハンドラーを実装する前に、ドライバー ライターは オーディオ ドライバー プロパティ セット を参照して、プロパティのターゲットをフィルター ハンドルまたはピン ハンドルとして指定する必要があるかどうかを確認する必要があります。
現在、Portcls.sys のポート ドライバーでは、KSPROPERTY_TOPOLOGY_NAMEを除き、ノード プロパティの組み込み処理は提供されていません。
指定超過および未指定のプロパティ要求
ドライバーは、上記の規則に従っていないクライアントからのプロパティ要求を処理するように準備する必要があります。 要求は、過剰に指定することも、指定が不足している場合もあります。
過剰に指定された要求
プロパティ要求で必要なのはフィルター ハンドルのみで、クライアントが代わりにピン ハンドルに要求を送信する場合、要求のターゲットは過剰に指定されます。 ただし、ドライバーは通常、要求を有効として扱います。つまり、要求は、ピンを含むフィルターに送信されたかのように扱われます。
指定されていない要求
プロパティ要求にピン ハンドルが必要であっても、クライアントが代わりにフィルター ハンドルに要求を送信する場合、要求のターゲットは指定されません。 たとえば、フィルターに同じノード型の複数のピン インスタンスが含まれており、クライアントがそのノード型のプロパティの要求をピン ハンドルではなくフィルター ハンドルに送信する場合、ドライバーは要求を受け取る必要があるノード インスタンスを決定する方法がありません。 この場合、動作はドライバーによって異なります。 一部のドライバーは、指定されていない要求をすべて自動的に失敗するのではなく、指定されていない set-property 要求を有効として扱います。 この場合、要求によって、指定されたノード ID の既定値が設定されます。 ピン ファクトリが新しいノード インスタンスを作成すると、新しいノードに属するプロパティが既定値に初期化されます。 既定値を変更する要求は、要求の前に作成されたノード インスタンスには影響しません。 さらに、ドライバーは、ハンドラーがプロパティに対してクエリを実行するノード インスタンスを決定する方法がないため、指定されていない get-property 要求を一様に失敗させます。
ルールの例外
歴史的な理由から、いくつかのオーディオ プロパティには、これらの一般的なルールに違反する動作の風変わりがあります。 次に例を示します。
「Speaker-Configuration 設定の適用」で説明されているように、クライアントは、3-D ノード (KSNODETYPE_3D_EFFECTS) の KSPROPERTY_AUDIO_CHANNEL_CONFIG プロパティを設定することで、オーディオ デバイスのスピーカー構成を変更できます。 スピーカー構成設定はグローバルです。これは、デバイスがスピーカーを介して再生するミックスの一部であるすべてのストリームのスピーカー構成を変更するためです。 一般的な規則に従って、フィルター全体に影響を与えるノード プロパティ要求では、フィルター ハンドル (およびノード ID) を指定する必要があります。 ただし、この特定のプロパティには、フィルター ハンドルではなくピン ハンドルが必要です。 ピン ハンドルは、要求のターゲットである 3-D ノードを含むピン インスタンスを指定します。
KSPROPERTY_SYNTH_VOLUME と KSPROPERTY_SYNTH_MASTERCLOCK は、シンセ ノード (KSNODETYPE_SYNTHESIZER) のプロパティです。 どちらもノード プロパティですが、これらのプロパティの要求にはノード ID は含まれません。 (要求のプロパティ記述子は KSNODEPROPERTY ではなく KSPROPERTY 型の構造体であることに注意してください)。この動作は、ノード プロパティにノード ID が必要であるという一般的な規則に違反します。 この不一致にもかかわらず、いずれかのプロパティをサポートするミニポート ドライバーは、(ピンのメンバーではなく) PCFILTER_DESCRIPTORの Nodes メンバーを介してプロパティ ハンドラーを提供する必要があります。