オーディオのプロパティに対してサポートされる基本的なクエリ

set-property 要求のデータをフィルター、ピン、またはノードに指定する場合、クライアントは、プロパティに対して指定する 1 つ以上の値の有効なデータ範囲を認識していることが、高い頻度で求められます。 範囲はデバイスによって異なり、場合によっては同じデバイス内のノード間でも異なる場合があります。

一部のプロパティは、範囲外の値を指定する set-property 要求を許可するように定義されていますが、ミニポート ドライバーは、サポートされている範囲にこれらの値を自動で固定します (例として、「KSPROPERTY_AUDIO_VOLUMELEVEL」を参照)。 同じプロパティに対する後続の get 要求では、1 つ以上の値に対するドライバーの実際の設定が取得されます。この値は、クライアントが set 要求で指定した値の固定されたバージョンである場合があります。

ただし、クライアントでは、単純にミニポート ドライバーを信頼して範囲外の値を自動的に固定するのではなく、プロパティ値の範囲を把握していることが必要である場合があります。 たとえば、オーディオ デバイスの音量制御スライダーを表示するウィンドウ アプリケーションでは、デバイスの音量範囲をスライダーの全長にマップするために、その音量範囲を把握している必要がある場合があります。

特定のプロパティのドライバーのハンドラー ルーチンは、基本サポート プロパティ要求 (KSPROPERTY_TYPE_BASICSUPPORT) に応答して範囲情報を提供できる必要があります。 基本サポート プロパティ要求をドライバーに送信する場合、クライアントは、プロパティ ハンドラーが基本サポート情報を書き込む値バッファーを提供します。この基本サポート情報は、プロパティ固有のデータが続く可能性のある KSPROPERTY_DESCRIPTION 構造体で構成されます。 このデータは通常、プロパティに応じて、1 つ以上のパラメーター範囲の仕様で構成されます。

一般に、クライアントは、この値バッファーの大きさを事前に把握していないため、値のサイズを決定するために、プロパティ ハンドラーに 1 つまたは 2 つの事前要求を送信する必要があります。 これらの仮要求の形式は明確に定義されています。 クライアントは、基本サポート要求を処理する際にドライバーが次の規則に従うことを想定しています。

• 要求で値のサイズが sizeof(ULONG) として指定されている場合、プロパティ ハンドラーは、KSPROPERTY_DESCRIPTION 構造体の AccessFlags メンバーの値を ULONG サイズの値バッファーに書き込む必要があります。 ハンドラーは、基本サポート プロパティ要求をさらにサポートする場合には、KSPROPERTY_TYPE_BASICSUPPORT フラグ ビットを設定します。

• 要求で値のサイズが sizeof(KSPROPERTY_DESCRIPTION) として指定されている場合、ハンドラーは KSPROPERTY_DESCRIPTION 構造体をデータ バッファーに書き込む必要があります。 ハンドラーは、構造体の DescriptionSize フィールドを、その構造体のサイズにハンドラが構造体に続いてデータ バッファにロードするために利用可能なプロパティ固有の追加情報すべてのサイズを加えたサイズに、等しく設定します。 これは、プロパティの基本サポート情報を格納するためにクライアントが割り当てる必要がある値バッファーのサイズです。

• 要求で、KSPROPERTY_DESCRIPTION 構造体とプロパティ固有の情報の両方を格納するのに十分な大きさの値サイズが指定されている場合、ハンドラーはバッファーの先頭に KSPROPERTY_DESCRIPTION 構造体を書き込む必要があり、KSPROPERTY_DESCRIPTION 構造体の末尾に続くデータ バッファーの部分にプロパティ固有の情報を書き込む必要があります。 KSPROPERTY_DESCRIPTION構造体を記述する場合、ハンドラーは DescriptionSize フィールドを、その構造体のサイズに、構造体に続くプロパティ固有の情報のサイズを加えたサイズに設定する必要があります。

要求で、これら 3 つのケースのいずれかに一致しない値のサイズが指定されている場合、プロパティ ハンドラーは要求を拒否し、状態コード STATUS_BUFFER_TOO_SMALL を返します。

ハンドラーが値バッファーに書き込むプロパティ固有の情報には、プロパティ値のデータ範囲が含まれる場合があります。 KSPROPERTY_MEMBERSHEADER の MembersSize メンバーは、データ範囲が含まれているかどうかを示します。

• 範囲が必要ない場合は、MembersSize は 0 です。 たとえば、プロパティ値が BOOL 型の場合がこれに該当します。

• KSPROPERTY_MEMBERSHEADER 構造体の後に 1 つ以上のプロパティ値の範囲記述子が続く場合、MembersSize は 0 以外になります。

BOOL 型のプロパティ値の場合、範囲は TRUE と FALSE の値に暗黙的に制限されるため、範囲記述子は必要ありません。 ただし、整数型でプロパティ値の範囲を指定するには、範囲記述子が必要です。

たとえば、ボリューム ノード (KSNODETYPE_VOLUME) の KSPROPERTY_AUDIO_VOLUMELEVEL プロパティに対する基本サポート要求では、そのノードの最小および最大ボリューム設定が取得されます。 この場合、クライアントは、次の構造体を格納するのに十分な大きさの値バッファーを割り当てる必要があります。

KSPROPERTY_DESCRIPTION

KSPROPERTY_MEMBERSLIST

KSPROPERTY_STEPPING_LONG

3 つの構造体は、前の一覧に示した順序でバッファー内の隣接する場所に収納されます。 要求を処理する際に、ミニポート ドライバーは、KSPROPERTY_STEPPING_LONG 構造体の Bounds メンバーに、最小および最大ボリューム レベルを書き込みます。

範囲記述子の配列を持つ基本サポート要求の例については、「マルチチャンネル ノードの公開」にある図を参照してください。 基本サポート プロパティ要求の詳細については、「KS プロパティ」を参照してください。 コード例については、Microsoft Windows Driver Kit (WDK) のサンプル オーディオ ドライバーのプロパティ ハンドラーの実装を参照してください。