Filter-, Pin- und Knoteneigenschaften
WdM-Audiotreiber (Microsoft Windows Driver Model) stellen ein Audiogerät als KS-Filter dar und stellen einen Hardwarepuffer auf dem Gerät als Anheftung am Filter dar. Wenn ein Client eine Eigenschaftsanforderung an eines dieser Filter- oder Pinobjekte sendet, empfängt der Porttreiber die Anforderung und leitet die Anforderung an den entsprechenden Eigenschaftenhandler im Porttreiber oder Miniporttreiber weiter.
Audiogeräte unterstützen drei Arten von Eigenschaften:
Filtereigenschaften
Eine Filtereigenschaft ist eine Eigenschaft des Filters als Ganzes und nicht eine Eigenschaft eines bestimmten Pins oder Knotens innerhalb des Filters. Anforderungen für Filtereigenschaften geben Filterhandles an, aber keine Knoten-IDs.
Eigenschaften anheften
Eine Pineigenschaft ist eine Eigenschaft eines bestimmten Pins instance für den Filter. Anforderungen für diese Eigenschaften geben Pinhandles an, aber keine Knoten-IDs.
Knoteneigenschaften
Eine Node-Eigenschaft ist eine Eigenschaft eines Topologieknotens innerhalb des Filters. Eine Anforderung für eine Node-Eigenschaft gibt einen Filterhandle oder Pinhandle sowie eine Knoten-ID an.
Ob eine Knoteneigenschaftsanforderung einen Filter- oder Pinhandle angibt, hängt davon ab, ob der Knoten für den Filter eindeutig ist. Weitere Informationen finden Sie im folgenden Abschnitt Knoteneigenschaften.
Die folgende Abbildung zeigt diese drei Arten von Eigenschaftsanforderungen: eine Anhefteigenschaftsanforderung, die an eine Pin-instance gesendet wird, eine Knoteneigenschaftenanforderung, die an einen Knoten (für einen Filter oder pin instance) gesendet wird, und eine Filtereigenschaftsanforderung, die an einen Filter instance gesendet wird.
In der Regel verarbeitet der Porttreiber die meisten Anforderungen für Filter- und Pineigenschaften, und der Miniporttreiber verarbeitet Anforderungen für Knoteneigenschaften.
Der Porttreiber stellt eigene integrierte Handler für die Filter- und Pineigenschaften bereit, die vom SysAudio-Systemtreiber (siehe KSPROPSETID_Sysaudio und KSPROPSETID_Sysaudio_Pin) und WDMAud-Systemtreiber verwendet werden. Ein Miniporttreiber muss keine Handler für Eigenschaften implementieren, die der Porttreiber verarbeitet. Ein typischer Miniporttreiber stellt, wenn überhaupt, einige Handler für Filter- und Pineigenschaften bereit. Der Miniporttreiber stellt die Handler für Knoteneigenschaften bereit, die hardwareabhängige Features des Audiogeräts darstellen. Die Porttreiber bieten keine integrierte Behandlung von Knoteneigenschaften, mit Ausnahme von KSPROPERTY_TOPOLOGY_NAME.
Wenn sowohl der Porttreiber als auch der Miniporttreiber Handler für dieselbe Eigenschaft bereitstellen, verwendet der Porttreiber seinen eigenen Handler und ignoriert den Handler des Miniporttreibers.
Filterdeskriptoren
Der Porttreiber ruft Zeiger auf die Eigenschaftenhandler des Miniporttreibers ab, indem er die IMiniport::GetDescription-Methode aufruft. Mit dieser Methode ruft der Porttreiber einen Zeiger auf den Filterdeskriptor des Miniporttreibers ab, der eine Struktur vom Typ PCFILTER_DESCRIPTOR ist. Diese Struktur gibt die Eigenschaftenhandler des Miniporttreibers für Filter-, Pin- und Knoteneigenschaften an:
Das AutomationTable-Element der PCFILTER_DESCRIPTOR-Struktur verweist auf die Automatisierungstabelle für den Filter. Diese Tabelle gibt die Eigenschaftenhandler des Miniporttreibers für Filtereigenschaften an.
Das Pins-Element der PCFILTER_DESCRIPTOR-Struktur enthält die Automatisierungstabellen für die Pins. Jede Tabelle gibt die Eigenschaftenhandler für die Pineigenschaften eines bestimmten Pintyps an.
Das Knotenelement der PCFILTER_DESCRIPTOR-Struktur enthält die Automatisierungstabellen für die Topologieknoten innerhalb des Filters. Jede Tabelle gibt die Eigenschaftenhandler für die Knoteneigenschaften eines bestimmten Knotentyps an.
Filtereigenschaften
Der Porttreiber greift über das AutomationTable-Element von PCFILTER_DESCRIPTOR auf die Filtereigenschaftenhandler des Miniporttreibers zu. In der Regel enthält diese Automatisierungstabelle nur wenige Handler, da der Porttreiber seine eigenen integrierten Handler für alle Filtereigenschaften bereitstellt, die SysAudio und WDMAud zum Abfragen und Konfigurieren von Audiogeräten verwenden.
Der Miniporttreiber kann jedoch Handler für Filtereigenschaften wie KSPROPERTY_GENERAL_COMPONENTID bereitstellen, die hardwareabhängige Informationen bereitstellen, die für den Porttreiber nicht verfügbar sind. Zwei der Beispielaudiotreiber im Microsoft Windows Driver Kit (WDK) behandeln die KSPROPERTY_GENERAL_COMPONENTID-Eigenschaft. Weitere Informationen finden Sie unter Miniporttreiberimplementierungen im Sysvad-Beispieltreiber, der unter Beispielaudiotreiber erläutert wird.
Alle Porttreiber in Portcls.sys ermöglichen die Verarbeitung der KSPROPSETID_Pin- und KSPROPSETID_Topology-Eigenschaftssätze. Alle Eigenschaften in diesen Sätzen sind Filtereigenschaften, mit Ausnahme von KSPROPERTY_TOPOLOGY_NAME, bei der es sich um eine Knoteneigenschaft handelt (die ein Filterhandle und kein Stifthandle verwendet, um das Ziel für die Anforderung anzugeben). Die Porttreiber unterstützen die folgende Teilmenge der KSPROPSETID_Pin Eigenschaften:
KSPROPERTY_PIN_CONSTRAINEDDATARANGES
KSPROPERTY_PIN_DATAINTERSECTION
KSPROPERTY_PIN_GLOBALCINSTANCES
KSPROPERTY_PIN_NECESSARYINSTANCES
KSPROPERTY_PIN_PHYSICALCONNECTION
KSPROPERTY_PIN_PROPOSEDATAFORMAT
KSPROPERTY_PIN_PROPOSEDATAFORMAT2
Diese Eigenschaften liefern Informationen zu den Pinfabriken, die zu einem Filter gehören. In der Regel fragen Clients den Filter nach diesen Eigenschaften ab, bevor Pininstanzen erstellt werden. Die Porttreiber unterstützen alle vier KSPROPSETID_Topology Eigenschaften, die Informationen zur internen Topologie des Filters bereitstellen.
Darüber hinaus stellt der DMus-Porttreiber einen Handler für die KSPROPERTY_SYNTH_MASTERCLOCK-Eigenschaft bereit, die eine get-only-Eigenschaft eines DirectMusic-Filters ist. KSPROPERTY_SYNTH_MASTERCLOCK ist ein Element des KSPROPSETID_SynthClock-Eigenschaftssatzes.
Eigenschaften anheften
Der Porttreiber greift über den Pins-Member von PCFILTER_DESCRIPTOR auf die Pin-Eigenschaftshandler des Miniporttreibers zu. Dieses Element verweist auf ein Array von Pindeskriptoren, und jeder Deskriptor zeigt auf die Automatisierungstabelle für einen Pintyp (identifiziert durch eine Pin-ID, die einfach den Arrayindex ist).
In der Regel enthalten diese Automatisierungstabellen nur wenige Einträge, da der Porttreiber eigene Handler für alle von SysAudio und WDMAud verwendeten Pineigenschaften bereitstellt. Ein Miniporttreiber hat die Möglichkeit, Handler für eine oder mehrere Pineigenschaften bereitzustellen, die der Porttreiber nicht verarbeitet, aber nur Clients, die über diese Eigenschaften wissen, können Eigenschaftenanforderungen für sie senden.
Mit Ausnahme des Topologieporttreibers stellen alle Porttreiber in Portcls.sys integrierte Handler für die folgenden Pineigenschaften bereit:
KSPROPERTY_CONNECTION_DATAFORMAT
KSPROPERTY_CONNECTION_ALLOCATORFRAMING
KSPROPERTY_DRMAUDIOSTREAM_CONTENTID
Einige der Eigenschaften in dieser Liste erfordern hardwareabhängige Informationen vom Miniporttreiber. Wenn der Porttreiber eine IRP empfängt, die eine Anforderung für eine dieser Eigenschaften enthält, übergibt er den IRP nicht an den Miniporttreiber. Stattdessen verarbeitet der Porttreiber die Anforderung selbst, aber sein Handler ruft die benötigten Informationen ab, indem er einen Einstiegspunkt im Miniporttreiber aufruft. Beispielsweise stellt der Porttreiber einen eigenen Eigenschaftenhandler für KSPROPERTY_AUDIO_POSITION Anforderungen bereit. Dieser Handler ruft einfach die GetPosition-Methode des Miniporttreiberstreams auf (z. B . IMiniportWavePciStream::GetPosition), um die aktuelle Position abzurufen.
Knoteneigenschaften
Der Porttreiber greift über das Knotenelement von PCFILTER_DESCRIPTOR auf die Knoteneigenschaftenhandler des Miniporttreibers zu. Dieses Element verweist auf ein Array von Knotendeskriptoren, und jeder Deskriptor zeigt auf die Automatisierungstabelle für einen Knotentyp (identifiziert durch eine Knoten-ID, die einfach den Arrayindex ist). In der Regel befinden sich alle oder die meisten Eigenschaftenhandler, die zu einem Miniporttreiber gehören, im Knotenarray . Ein Audiotreiber stellt die Hardwaresteuerelemente in einem Audiogerät als Topologieknoten dar und verwendet den Eigenschaftsmechanismus, um Clients Zugriff auf die hardwareabhängigen Steuerungseinstellungen zu gewähren.
Wie bereits beschrieben, sendet ein Client eine Filtereigenschaftsanforderung an ein Filterhandle und eine Pin-Eigenschaftsanforderung an ein Pinhandle. Im Gegensatz zu einem Filter- oder Pin-instance ist ein Knoten kein Kernelobjekt und verfügt nicht über ein Handle. Ein Client sendet eine Node-Eigenschaftsanforderung entweder an ein Pinhandle oder ein Filterhandle, aber die Anforderung gibt auch eine Knoten-ID an, um anzugeben, dass die Anforderung für eine Knoteneigenschaft und nicht für eine Pin- oder Filtereigenschaft gilt.
Die folgenden allgemeinen Regeln bestimmen, ob eine Knoteneigenschaft ein Filterhandle oder ein Pinhandle verwenden soll:
Wenn ein Filter mehrere Instanzen eines bestimmten Pintyps enthält und jeder Pin dieses Typs einen Knoten mit einer bestimmten Knoten-ID enthält, enthält jeder Pin instance eine instance des Knotens. In diesem Fall muss eine Node-Eigenschaftsanforderung ein Pinhandle (und nicht nur ein Filterhandle) angeben, um zwischen mehreren Instanzen desselben Knotentyps zu unterscheiden. Die Kombination aus Stifthandle und Knoten-ID identifiziert eindeutig einen bestimmten Knoten instance als Ziel für die Anforderung.
Wenn ein Filter nur einen instance eines bestimmten Knotens enthält, gibt eine Knoteneigenschaftsanforderung ein Filterhandle an. Die Kombination aus Filterhandle und Knoten-ID reicht aus, um den Knoten eindeutig zu identifizieren, der das Ziel für die Anforderung ist.
Vor der Implementierung eines Handlers für eine bestimmte Knoteneigenschaft sollte der Treiberschreiber jedoch auf Audiotreiber-Eigenschaftssätze verweisen, um zu überprüfen, ob das Ziel für die Eigenschaft als Filterhandle oder Stifthandle angegeben werden soll.
Die Porttreiber in Portcls.sys bieten derzeit keine integrierte Behandlung von Knoteneigenschaften, mit Ausnahme von KSPROPERTY_TOPOLOGY_NAME.
Über- und unterspezifische Eigenschaftenanforderungen
Treiber sollten darauf vorbereitet sein, Eigenschaftenanforderungen von Clients zu verarbeiten, die nicht den vorherigen Regeln entsprechen. Anforderungen können entweder über- oder nicht angegeben sein:
Überspezifische Anforderungen
Wenn für eine Eigenschaftsanforderung nur ein Filterhandle erforderlich ist, der Client die Anforderung jedoch stattdessen an ein Pinhandle sendet, wird das Ziel für die Anforderung überdekliniert. Treiber behandeln die Anforderung jedoch in der Regel als gültig. Das heißt, sie behandeln die Anforderung so, als ob sie an den Filter gesendet worden wäre, der den Pin enthält.
Unterbestimmte Anforderungen
Wenn für eine Eigenschaftsanforderung ein Pinhandle erforderlich ist, aber ein Client die Anforderung stattdessen an ein Filterhandle sendet, wird das Ziel für die Anforderung nicht angegeben. Wenn beispielsweise ein Filter mehrere Pininstanzen mit demselben Knotentyp enthält und ein Client eine Anforderung für eine Eigenschaft dieses Knotentyps anstelle eines Pinhandles an ein Filterhandle sendet, kann der Treiber nicht bestimmen, welcher Knoten instance die Anforderung empfangen soll. In diesem Fall hängt das Verhalten vom Treiber ab. Anstatt automatisch alle nicht angegebenen Anforderungen zu verfehlen, behandeln einige Treiber eine nicht angegebene Set-Eigenschaftsanforderung als gültig. In diesem Fall wird interpretiert, dass die Anforderung den Standardwert für die angegebene Knoten-ID festlegt. Wenn eine Pinfactory einen neuen Knoten instance erstellt, wird die Eigenschaft, die zum neuen Knoten gehört, mit dem Standardwert initialisiert. Eine Anforderung, die den Standardwert ändert, hat keine Auswirkungen auf Knoteninstanzen, die vor der Anforderung erstellt wurden. Darüber hinaus schlagen Treiber unterspezifische get-property-Anforderungen einheitlich fehl, da der Handler keine Möglichkeit hat, zu bestimmen, welcher Knoten instance, um die Eigenschaft abzufragen.
Ausnahmen von den Regeln
Aus historischen Gründen weisen einige Audioeigenschaften Verhaltensstörungen auf, die gegen diese allgemeinen Regeln verstoßen. Hier finden Sie einige Beispiele:
Wie unter Anwenden Speaker-Configuration Einstellungen beschrieben, kann ein Client die Lautsprecherkonfiguration eines Audiogeräts ändern, indem er die eigenschaft KSPROPERTY_AUDIO_CHANNEL_CONFIG eines 3D-Knotens (KSNODETYPE_3D_EFFECTS) festlegt. Die Einstellung für die Lautsprecherkonfiguration ist global, da sie die Lautsprecherkonfiguration für alle Streams ändert, die Teil der Mischung sind, die das Gerät über die Lautsprecher abspielt. Gemäß der allgemeinen Regel sollte eine Node-Eigenschaftsanforderung, die sich auf den Filter als Ganzes auswirkt, ein Filterhandle (plus knoten-ID) angeben. Diese spezielle Eigenschaft erfordert jedoch ein Stifthandle anstelle eines Filterhandles. Der Stiftziehpunkt legt den Pin instance fest, der den 3D-Knoten enthält, der das Ziel für die Anforderung ist.
KSPROPERTY_SYNTH_VOLUME und KSPROPERTY_SYNTH_MASTERCLOCK sind Eigenschaften eines Synthieknotens (KSNODETYPE_SYNTHESIZER). Obwohl beide Knoteneigenschaften sind, enthalten Anforderungen für diese Eigenschaften keine Knoten-IDs. (Beachten Sie, dass der Eigenschaftendeskriptor für die Anforderung eine Struktur vom Typ KSPROPERTY und nicht KSNODEPROPERTY ist.) Dieses Verhalten verstößt gegen die allgemeine Regel, dass eine Knoteneigenschaft eine Knoten-ID erfordert. Trotz dieser Diskrepanz sollte ein Miniporttreiber, der beide Eigenschaften unterstützt, den Eigenschaftenhandler über den Knotenmember von PCFILTER_DESCRIPTOR (anstelle des Pins-Elements ) bereitstellen.
Feedback
Bald verfügbar: Im Laufe des Jahres 2024 werden wir GitHub-Issues stufenweise als Feedbackmechanismus für Inhalte abbauen und durch ein neues Feedbacksystem ersetzen. Weitere Informationen finden Sie unter https://aka.ms/ContentUserFeedback.
Feedback senden und anzeigen für