音訊屬性的基本支援查詢

針對篩選、釘選或節點指定 set-property 要求的資料時,用戶端經常需要知道其為 屬性指定之值或值的有效資料範圍。 範圍可能會因裝置而異,甚至可能從相同裝置內的節點到節點。

某些屬性的定義是允許 set-property requests 指定超出範圍的值,但迷你埠驅動程式會以無訊息方式將這些值固定在支援的範圍 (,例如,請參閱 KSPROPERTY_AUDIO_VOLUMELEVEL) 。 相同屬性的後續取得要求會擷取值或值的驅動程式實際設定,這些值可能是用戶端在設定要求中指定的值版本。

不過,用戶端可能需要知道屬性值的範圍,而不需要只依賴迷你埠驅動程式來自動限制超出範圍的值。 例如,顯示音訊裝置音量控制滑杆的視窗化應用程式可能需要知道裝置的音量範圍,才能將該範圍對應至滑杆的完整長度。

特定屬性的驅動程式處理常式常式應該能夠提供範圍資訊,以回應基本支援屬性要求 (KSPROPERTY_TYPE_BASICSUPPORT) 。 將基本支援屬性要求傳送至驅動程式時,用戶端會提供值緩衝區,讓屬性處理常式寫入基本支援資訊,其中包含可能後面接著屬性特定資料的 KSPROPERTY_DESCRIPTION 結構。 根據 屬性,此資料通常包含一或多個參數範圍的規格。

一般而言,用戶端事先不知道此值緩衝區的大小,而且必須將一或兩個初步要求傳送至屬性處理常式,以判斷值大小。 這些初步要求的格式已妥善定義。 用戶端預期驅動程式會在處理基本支援要求時遵循這些慣例:

  • 如果要求將值大小指定為 sizeof (ULONG) ,則屬性處理常式應該將 KSPROPERTY_DESCRIPTION 結構的 AccessFlags 成員值寫入 ULONG 大小的值緩衝區。 如果處理常式提供基本支援屬性要求的進一步支援,則處理常式會設定KSPROPERTY_TYPE_BASICSUPPORT旗標位。

  • 如果要求將值大小指定為 sizeof (KSPROPERTY_DESCRIPTION) ,處理常式應該將KSPROPERTY_DESCRIPTION結構寫入資料緩衝區。 處理常式會將 結構的 DescriptionSize 欄位設定為等於該結構的大小,加上處理常式在結構之後載入資料緩衝區中所有額外屬性特定資訊的大小。 這是用戶端必須配置以包含屬性基本支援資訊的值緩衝區大小。

  • 如果要求指定大到足以同時包含KSPROPERTY_DESCRIPTION結構和屬性特定資訊的值大小,處理常式應該將KSPROPERTY_DESCRIPTION結構寫入緩衝區開頭,而且應該將屬性特定資訊寫入KSPROPERTY_DESCRIPTION結構結尾的資料緩衝區部分。 撰寫KSPROPERTY_DESCRIPTION結構時,處理常式應將 DescriptionSize 欄位設定為該結構的大小,加上結構後面的屬性特定資訊大小。

如果要求指定的值大小不符合這三個案例的其中一個,則屬性處理常式會拒絕要求,並傳回狀態碼STATUS_BUFFER_TOO_SMALL。

處理常式寫入值緩衝區的屬性特定資訊可能包含屬性值的資料範圍。 KSPROPERTY_MEMBERSHEADER的 MembersSize 成員會指出是否包含資料範圍:

  • 如果不需要任何範圍,MembersSize就會是零。 例如,如果屬性值的類型為 BOOL,則為這種情況。

  • 如果KSPROPERTY_MEMBERSHEADER結構後面接著一或多個屬性值的範圍描述項,則 MembersSize為非零。

如果是 BOOL 類型的屬性值,則不需要範圍描述元,因為範圍會隱含限制為 TRUEFALSE值。 不過,需要範圍描述元,才能指定具有整數類型的屬性值範圍。

例如,磁片區節點上 KSPROPERTY_AUDIO_VOLUMELEVEL 屬性的基本支援要求 (KSNODETYPE_VOLUME) 會擷取該節點的最小和最大磁片區設定。 在此情況下,用戶端必須配置足以包含下列結構的值緩衝區:

KSPROPERTY_DESCRIPTION

KSPROPERTY_MEMBERSLIST

KSPROPERTY_STEPPING_LONG

這三個結構會以上述清單中顯示的順序,封裝到緩衝區中的相鄰位置。 處理要求時,迷你埠驅動程式會將最小和最大磁片區層級寫入KSPROPERTY_STEPPING_LONG結構的 Bounds 成員。

如需具有範圍描述元陣列的基本支援要求範例,請參閱 公開多重通道節點中的圖表。 如需基本支援屬性要求的詳細資訊,請參閱 KS 屬性。 如需程式碼範例,請參閱 Microsoft Windows Driver Kit (WDK) 範例 音訊驅動程式 中的屬性處理常式實作。