Hinweis
Für den Zugriff auf diese Seite ist eine Autorisierung erforderlich. Sie können versuchen, sich anzumelden oder das Verzeichnis zu wechseln.
Für den Zugriff auf diese Seite ist eine Autorisierung erforderlich. Sie können versuchen, das Verzeichnis zu wechseln.
Wenn Sie die Daten für eine Set-Property-Anforderung für einen Filter, einen Pin oder einen Knoten angeben, muss der Client häufig die gültigen Datenbereiche für den Wert oder die Werte kennen, die er für die Eigenschaft angibt. Bereiche können von Gerät zu Gerät variieren und möglicherweise sogar von Knotenpunkt zu Knotenpunkt innerhalb desselben Geräts.
Einige Eigenschaften sind so definiert, dass Set-Property-Anforderungen Werte angeben können, die außerhalb des Bereichs liegen. Miniporttreiber klammern diese Werte jedoch im Hintergrund an den unterstützten Bereich (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, die möglicherweise Klammerversionen der Werte sein können, die der Client in der Setanforderung angegeben hat.
Ein Client muss jedoch möglicherweise den Bereich für einen Eigenschaftswert kennen, anstatt einfach auf den Miniporttreiber zu vertrauen, der einen Wert, der außerhalb des Bereichs liegt, automatisch begrenzt. Beispielsweise muss eine Fensteranwendung, die einen Lautstärkeregler für ein Audiogerät darstellt, möglicherweise den Lautstärkebereich des Geräts kennen, um diesen Bereich der gesamten Länge des Schiebereglers zuzuordnen.
Die Handlerroutine des Treibers für eine bestimmte Eigenschaft sollte in der Lage sein, Bereichsinformationen als Reaktion auf eine Anforderung einer grundlegenden Unterstützungseigenschaft (KSPROPERTY_TYPE_BASICSUPPORT) bereitzustellen. Beim Senden einer Anforderung einer Basisunterstützungseigenschaft an einen Treiber stellt ein Client einen Wertpuffer bereit, in den der Eigenschaftenhandler die grundlegenden Supportinformationen 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 im Voraus nicht, wie groß dieser Wertpuffer sein soll, und muss eine oder zwei vorläufige Anforderungen an den Eigenschaftenhandler senden, um die Wertgröße zu bestimmen. Das Format für diese vorläufigen Anforderungen ist klar definiert. Clients erwarten, dass Treiber bei der Behandlung einer grundlegenden Supportanfrage diese Konventionen einhalten:
Wenn die Anforderung die Wertgröße als sizeof(ULONG) angibt, sollte der Eigenschaftenhandler den Wert des AccessFlags-Elements der KSPROPERTY_DESCRIPTION Struktur in den ULONG-Größen-Wertpuffer schreiben. Der Handler legt das KSPROPERTY_TYPE_BASICSUPPORT-Flag-Bit fest, wenn er weitere Unterstützung für die Anfragen zu Grundeigenschaften 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 auf die Größe dieser Struktur sowie die Größe aller zusätzlichen eigenschaftenspezifischen Informationen fest, die der Handler nach der Struktur in den Datenpuffer laden kann. Dies ist die Größe des Wertpuffers, den der Client zuordnen muss, um die grundlegenden Supportinformationen 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 auf das Ende der KSPROPERTY_DESCRIPTION Struktur folgt. Beim Schreiben der KSPROPERTY_DESCRIPTION-Struktur sollte der Handler das DescriptionSize-Feld auf die Größe dieser Struktur und 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 den Statuscode STATUS_BUFFER_TOO_SMALL zurück.
Die eigenschaftsspezifischen Informationen, die der Handler in den Wertpuffer schreibt, kann 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 nicht null, wenn die KSPROPERTY_MEMBERSHEADER Struktur von Bereichsdeskriptoren für einen oder mehrere Eigenschaftswerte folgt.
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 ganzzahligen Typen anzugeben.
Beispielsweise ruft die Basisunterstützungsanforderung für eine KSPROPERTY_AUDIO_VOLUMELEVEL-Eigenschaft auf einem Volumeknoten (KSNODETYPE_VOLUME) die Mindest- und Maximale Volumeeinstellungen für diesen Knoten ab. In diesem Fall muss der Client einen Wertpuffer zuweisen, der groß genug ist, um die folgenden Strukturen zu enthalten:
Die drei Strukturen werden in angrenzende Speicherorte im Puffer in der reihenfolge verpackt, die in der vorherigen Liste angezeigt wird. Bei der Bearbeitung der Anforderung schreibt der Miniporttreiber die minimalen und maximalen Lautstärkepegel in das Bounds-Element der KSPROPERTY_STEPPING_LONG-Struktur.
Ein Beispiel für eine einfache Supportanfrage mit einem Array von Bereichsdeskriptoren finden Sie in der Abbildung in Exposing Multichannel Nodes. Weitere Informationen zu Standard-Support-Eigenschaftsanfragen finden Sie unter KS-Eigenschaften. Codebeispiele finden Sie in den Eigenschaftenhandlerimplementierungen in den Beispielaudiotreibern im Microsoft Windows Driver Kit (WDK).