次の方法で共有

フィルター、ピン、ノードのプロパティ

  • [アーティクル]

Microsoft Windows Driver Model (WDM) オーディオ ドライバーは、オーディオ デバイスを KS フィルターとして表し、デバイス上のハードウェア バッファーをフィルターのピンとして表します。 クライアントがこれらのフィルターまたはピン オブジェクトのいずれかにプロパティ要求を送信すると、ポート ドライバーは要求を受け取り、ポート ドライバーまたはミニポート ドライバーの適切なプロパティ ハンドラーに要求をルーティングします。

オーディオ デバイスでは次の 3 種類のプロパティがサポートされています。

  • フィルター プロパティ

    フィルター プロパティは、フィルター内の特定のピンまたはノードのプロパティではなくフィルター全体のプロパティです。 フィルター プロパティの要求は、フィルター ハンドルを指定しますが、ノード ID は指定しません。

  • ピン プロパティ

    ピン プロパティは、フィルター上の特定のピン インスタンスのプロパティです。 これらのプロパティの要求は、フィルター ハンドルを指定しますが、ノード ID は指定しません。

  • ノードのプロパティ

    ノード プロパティは、フィルター内のトポロジ ノードのプロパティです。 ノード プロパティの要求は、フィルター ハンドルまたはピン ハンドルとノード ID を指定します。

ノード プロパティ要求でフィルター ハンドルまたはピン ハンドルを指定するかどうかは、ノードがフィルターに対して一意かどうかによって異なります。 詳細については、次の「ノード プロパティ」セクションを参照してください。

次の図は、3 種類のプロパティ要求、つまりピン インスタンスに送信されるピン プロパティ要求、ノードに送信されたノード プロパティ要求 (フィルターまたはピン インスタンス上)、フィルター インスタンスに送信されるフィルター プロパティ要求を示しています。

Diagram illustrating filter, pin, and node property requests.

ポート ドライバーは通常、フィルターとピンのプロパティのほとんどの要求を処理し、ミニポート ドライバーは、ノードのプロパティの要求を処理します。

ポート ドライバーは、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_CATEGORY

KSPROPERTY_PIN_CINSTANCES

KSPROPERTY_PIN_COMMUNICATION

KSPROPERTY_PIN_CONSTRAINEDDATARANGES

KSPROPERTY_PIN_CTYPES

KSPROPERTY_PIN_DATAFLOW

KSPROPERTY_PIN_DATAINTERSECTION

KSPROPERTY_PIN_DATARANGES

KSPROPERTY_PIN_GLOBALCINSTANCES

KSPROPERTY_PIN_INTERFACES

KSPROPERTY_PIN_MEDIUMS

KSPROPERTY_PIN_NAME

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 の Pins メンバーを介してミニポート ドライバーのピン プロパティ ハンドラーにアクセスします。 このメンバーはピン記述子の配列をポイントし、各記述子はピンの種類のオートメーション テーブルをポイントします (ピン ID で識別されます。ピン ID は配列インデックスにすぎません)。

ポート ドライバーは SysAudio と WDMAud により使用されるすべてのピン プロパティに対して独自のハンドラーを提供するため、通常、これらのオートメーション テーブルにはいくつかのエントリが含まれています。 ミニポート ドライバーには、ポート ドライバーが処理しない 1 つ以上の ピン プロパティのハンドラーを提供するオプションがありますが、これらのプロパティを知っているクライアントのみが、それらのプロパティ要求を送信できます。

トポロジ ポート ドライバーを除き、Portcls.sys のすべてのポート ドライバーは、以下のピン プロパティの組み込みハンドラーを提供します。

KSPROPERTY_CONNECTION_STATE

KSPROPERTY_CONNECTION_DATAFORMAT

KSPROPERTY_CONNECTION_ALLOCATORFRAMING

KSPROPERTY_STREAM_ALLOCATOR

KSPROPERTY_STREAM_MASTERCLOCK

KSPROPERTY_AUDIO_POSITION

KSPROPERTY_DRMAUDIOSTREAM_CONTENTID

この一覧のプロパティの一部には、ミニポート ドライバーからのハードウェアに依存する情報が必要です。 ポート ドライバーは、これらのいずれかのプロパティの要求を含む IRP を受信すると、ミニポート ドライバーに IRP を渡しません。 代わりに、ポート ドライバーは要求自体を処理しますが、そのハンドラーは、ミニポート ドライバーのエントリ ポイントを呼び出すことによって必要な情報を取得します。 たとえば、ポート ドライバーは、KSPROPERTY_AUDIO_POSITION 要求に対して独自のプロパティ ハンドラーを提供します。 このハンドラーは、ミニポート ドライバー ストリームの GetPosition メソッド (IMiniportWavePciStream::GetPosition など) を呼び出して現在の位置を取得するだけです。

ノードのプロパティ

ポート ドライバーは、PCFILTER_DESCRIPTOR の Nodes メンバーを介してミニポート ドライバーのノード プロパティ ハンドラーにアクセスします。 このメンバーはノード記述子の配列をポイントし、各記述子はノードの種類のオートメーション テーブルをポイントします (ノード ID で識別されます。ノード ID は配列インデックスにすぎません)。 通常、ミニポート ドライバーに属するプロパティ ハンドラーのすべてまたはほとんどは、Nodes 配列に存在します。 オーディオ ドライバーは、オーディオ デバイス内のハードウェア コントロールをトポロジ ノードとして表し、プロパティ メカニズムを使用して、ハードウェア依存コントロール設定へのアクセスをクライアントに提供します。

前述のように、クライアントはフィルター プロパティ要求をフィルター ハンドルに送信し、ピン プロパティ要求をピン ハンドルに送信します。 フィルターまたはピン インスタンスとは異なり、ノードはカーネル オブジェクトではなく、ハンドルを持っていません。 クライアントは、ノード プロパティ要求をピン ハンドルまたはフィルター ハンドルに送信しますが、要求は、要求がピンまたはフィルター プロパティではなくノード プロパティ用であることを示すノード ID も指定します。

ノード プロパティがフィルター ハンドルまたはピン ハンドルを使用する必要があるかどうかを判断するための一般的なルールを次に示します。

  • フィルターに特定のピンの種類のインスタンスが複数含まれており、その種類の各ピンに特定のノード ID を持つノードが含まれている場合、各ピン インスタンスにはノードのインスタンスが含まれます。 この場合、ノード プロパティ要求では、同じノードの種類の複数のインスタンスを区別するため、(フィルター ハンドルではなく) ピン ハンドルを指定する必要があります。 ピン ハンドルとノード ID の組み合わせによって、特定のノード インスタンスが要求のターゲットとして明確に識別されます。

  • 特定のノードのインスタンスが 1 つだけフィルターに含まれている場合、ノード プロパティ要求はフィルター ハンドルを指定します。 フィルター ハンドルとノード ID の組み合わせは、要求のターゲットであるノードを明確に識別するのに十分です。

ただし、特定のノード プロパティのハンドラーを実装する前に、ドライバー ライターはオーディオ ドライバー プロパティ セットを参照し、プロパティのターゲットをフィルター ハンドルまたはピン ハンドルとして指定するかどうかをチェックする必要があります。

現在のところ、Portcls.sys のポート ドライバーは、KSPROPERTY_TOPOLOGY_NAME を除き、ノード プロパティの組み込み処理を提供していません。

指定過剰および指定不足のプロパティ要求

ドライバーは、上記のルールに従っていないクライアントからのプロパティ要求を処理するよう準備する必要があります。 要求は、指定過剰のことも指定不足のこともあります。

  • 指定過剰の要求

    プロパティ要求に必要なのはフィルター ハンドルのみで、クライアントが代わりにピン ハンドルに要求を送信する場合、要求のターゲットは過剰に指定されます。 ただし、通常ドライバーは要求を有効として扱います。つまり、要求は、ピンを含むフィルターに送信されたかのように扱われます。

  • 指定不足の要求

    プロパティ要求にピン ハンドルが必要であるが、クライアントが代わりにフィルター ハンドルに要求を送信する場合、要求のターゲットは指定不十分になります。 たとえば、フィルターに同じノードの種類のピン インスタンスが複数含まれており、クライアントがそのノードの種類のプロパティの要求をピン ハンドルではなくフィルター ハンドルに送信する場合、ドライバーには、要求を受け取る必要があるノード インスタンスを判断する方法がありません。 この場合、動作はドライバーによって異なります。 一部のドライバーは、指定不十分な要求をすべて自動的に失敗として扱うのではなく、指定不十分な設定プロパティ要求を有効として扱います。 この場合、指定されたノード ID の既定値が要求によって設定されると解釈されます。 ピン ファクトリが新しいノード インスタンスを作成すると、新しいノードに属するプロパティが既定値に初期化されます。 既定値を変更する要求は、要求前に作成されたノード インスタンスには影響を与えません。 さらに、ハンドラーには、プロパティに対してクエリを実行するノード インスタンスを判断する方法がないため、ドライバーは指定不十分な取得プロパティ要求を一様に失敗として扱います。

ルールの例外

歴史的な理由から、いくつかのオーディオ プロパティには、これらの一般的なルールに違反する特異な動作があります。 エントリにはたとえば次のような種類があります。

  • 「スピーカー構成設定の適用」で説明されているように、クライアントは、3-D ノード (KSNODETYPE_3D_EFFECTS) の KSPROPERTY_AUDIO_CHANNEL_CONFIG プロパティを設定することにより、オーディオ デバイスのスピーカー構成を変更できます。 スピーカー構成設定は、デバイスがスピーカーを介して再生するミックスの一部であるすべてのストリームのスピーカー構成を変更するため、グローバルです。 一般的なルールに従って、フィルター全体に影響を与えるノード プロパティ要求は、フィルター ハンドル (およびノード ID) を指定する必要があります。 ただし、この特定のプロパティには、フィルター ハンドルではなくピン ハンドルが必要です。 ピン ハンドルは、要求のターゲットである 3-D ノードを含むピン インスタンスを指定します。

  • KSPROPERTY_SYNTH_VOLUME と KSPROPERTY_SYNTH_MASTERCLOCK は、synth ノード (KSNODETYPE_SYNTHESIZER) のプロパティです。 どちらもノード プロパティですが、これらのプロパティの要求にはノード ID は含まれていません。 (要求のプロパティ記述子は型 KSNODEPROPERTY ではなく KSPROPERTY の構造である点に注意してください)。この動作は、ノード プロパティにノード ID が必要であるという一般的なルールに違反しています。 この不一致にもかかわらず、いずれかのプロパティをサポートするミニポート ドライバーは、(Pins メンバーではなく) PCFILTER_DESCRIPTOR の Nodes メンバーを介してプロパティ ハンドラーを提供する必要があります。