Grundlegende Supportabfragen für Audioeigenschaften

Beim Angeben der Daten für eine Set-Property-Anforderung an einen Filter, Anheften oder Knoten muss der Client häufig die gültigen Datenbereiche für den Wert oder die Werte kennen, die er für die Eigenschaft angibt. Die Bereiche können von Gerät zu Gerät und möglicherweise sogar von Knoten zu Knoten innerhalb desselben Geräts variieren.

Einige Eigenschaften sind so definiert, dass Set-Property-Anforderungen Werte angeben können, die außerhalb des Bereichs liegen, aber Miniporttreiber klammern diese Werte im Hintergrund in den unterstützten Bereich ein (siehe z. B. KSPROPERTY_AUDIO_VOLUMELEVEL). Eine nachfolgende Get-Anforderung für dieselbe Eigenschaft ruft die tatsächlichen Einstellungen des Treibers für den Wert oder die Werte ab. Dabei kann es sich um geklammerte Versionen der Werte handeln, die der Client in der Set-Anforderung angegeben hat.

Ein Client muss jedoch möglicherweise den Bereich für einen Eigenschaftswert kennen, anstatt sich einfach auf den Miniporttreiber zu verlassen, um einen Wert außerhalb des Bereichs automatisch zu klammern. Beispielsweise muss eine Anwendung mit Fenstern, die einen Lautstärkeregler für ein Audiogerät darstellt, möglicherweise den Lautstärkebereich des Geräts kennen, um diesen Bereich der vollständigen Länge des Schiebereglers zuzuordnen.

Die Handlerroutine des Treibers für eine bestimmte Eigenschaft sollte in der Lage sein, Bereichsinformationen als Reaktion auf eine Basisunterstützungseigenschaftsanforderung (KSPROPERTY_TYPE_BASICSUPPORT) bereitzustellen. Beim Senden einer Basic-Support-Eigenschaftsanforderung an einen Treiber stellt ein Client einen Wertpuffer bereit, in den der Eigenschaftshandler die grundlegenden Unterstützungsinformationen schreibt, die aus einer KSPROPERTY_DESCRIPTION-Struktur bestehen, auf die eigenschaftenspezifische Daten folgen können. Diese Daten bestehen in der Regel aus Spezifikationen für einen oder mehrere Parameterbereiche, je nach Eigenschaft.

Im Allgemeinen weiß der Client nicht im Voraus, wie groß dieser Wertpuffer sein soll, und muss eine oder zwei vorläufige Anforderungen an den Eigenschaftshandler senden, um die Wertgröße zu bestimmen. Das Format für diese Vorläufigen Anforderungen ist klar definiert. Clients erwarten, dass Treiber diese Konventionen befolgen, wenn sie eine Basic-Support-Anforderung verarbeiten:

• Wenn die Anforderung die Wertgröße als sizeof(ULONG) angibt, sollte der Eigenschaftshandler den Wert des AccessFlags-Elements der KSPROPERTY_DESCRIPTION-Struktur in den Wertpuffer mit ULONG-Größe schreiben. Der Handler legt das KSPROPERTY_TYPE_BASICSUPPORT-Flagbit fest, wenn er weitere Unterstützung für Basic-Support-Eigenschaftenanforderungen bietet.

• Wenn die Anforderung die Wertgröße als sizeof(KSPROPERTY_DESCRIPTION) angibt, sollte der Handler eine KSPROPERTY_DESCRIPTION-Struktur in den Datenpuffer schreiben. Der Handler legt das DescriptionSize-Feld der Struktur gleich der Größe dieser Struktur sowie die Größe aller zusätzlichen eigenschaftenspezifischen Informationen fest, die der Handler zum Laden in den Datenpuffer nach der Struktur zur Verfügung hat. Dies ist die Größe des Wertpuffers, den der Client zuordnen muss, um die Basisunterstützungsinformationen der Eigenschaft zu enthalten.

• Wenn die Anforderung eine Wertgröße angibt, die groß genug ist, um sowohl die KSPROPERTY_DESCRIPTION-Struktur als auch die eigenschaftenspezifischen Informationen zu enthalten, sollte der Handler die KSPROPERTY_DESCRIPTION-Struktur in den Anfang des Puffers schreiben und die eigenschaftsspezifischen Informationen in den Teil des Datenpuffers schreiben, der dem Ende der KSPROPERTY_DESCRIPTION-Struktur folgt. Beim Schreiben der KSPROPERTY_DESCRIPTION-Struktur sollte der Handler das DescriptionSize-Feld auf die Größe dieser Struktur plus die Größe der eigenschaftenspezifischen Informationen festlegen, die der Struktur folgen.

Wenn die Anforderung eine Wertgröße angibt, die nicht mit einem dieser drei Fälle übereinstimmt, lehnt der Eigenschaftenhandler die Anforderung ab und gibt status Code STATUS_BUFFER_TOO_SMALL zurück.

Die eigenschaftsspezifischen Informationen, die der Handler in den Wertpuffer schreibt, können Datenbereiche für Eigenschaftswerte enthalten. Das MembersSize-Element von KSPROPERTY_MEMBERSHEADER gibt an, ob Datenbereiche enthalten sind:

• MembersSize ist null, wenn keine Bereiche benötigt werden. Dies ist beispielsweise der Fall, wenn Eigenschaftswerte vom Typ BOOL sind.

• MembersSize ist ungleich null, wenn auf die KSPROPERTY_MEMBERSHEADER-Struktur bereichsdeskriptoren für einen oder mehrere Eigenschaftswerte folgen.

Für einen Eigenschaftswert vom Typ BOOL ist kein Bereichsdeskriptor erforderlich, da der Bereich implizit auf die Werte TRUE und FALSE beschränkt ist. Bereichsdeskriptoren sind jedoch erforderlich, um die Bereiche von Eigenschaftswerten mit Ganzzahltypen anzugeben.

Beispielsweise ruft die Basic-Support-Anforderung für eine KSPROPERTY_AUDIO_VOLUMELEVEL-Eigenschaft auf einem Volumeknoten (KSNODETYPE_VOLUME) die Einstellungen für das minimale und maximale Volume für diesen Knoten ab. In diesem Fall muss der Client einen Wertpuffer zuordnen, der groß genug ist, um die folgenden Strukturen zu enthalten:

KSPROPERTY_DESCRIPTION

KSPROPERTY_MEMBERSLIST

KSPROPERTY_STEPPING_LONG

Die drei Strukturen werden in der reihenfolge, die in der vorherigen Liste dargestellt ist, in benachbarten Speicherorten im Puffer gepackt. Bei der Verarbeitung der Anforderung schreibt der Miniporttreiber die minimalen und maximalen Lautstärkestufen in den Bounds-Member der KSPROPERTY_STEPPING_LONG-Struktur.

Ein Beispiel für eine Basic-Support-Anforderung mit einem Array von Bereichsdeskriptoren finden Sie in der Abbildung unter Verfügbarmachen von Multichannelknoten. Weitere Informationen zu Grundlegenden Unterstützungseigenschaftenanforderungen finden Sie unter KS-Eigenschaften. Codebeispiele finden Sie in den Eigenschaftenhandlerimplementierungen in den Beispiel-Audiotreibern im Microsoft Windows Driver Kit (WDK).