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.
Microsoft Windows Driver Model (WDM)-Audiotreiber stellen ein Audiogerät als KS-Filter dar und stellen einen Hardwarepuffer auf dem Gerät als Pin auf dem Filter dar. Wenn ein Client eine Eigenschaftsanforderung an einen 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 anstelle einer Eigenschaft eines bestimmten Pins oder Knotens innerhalb des Filters. Anforderungen für Filtereigenschaften geben Filterhandles an, geben jedoch keine Knoten-IDs an.
Pin-Eigenschaften
Eine Pineigenschaft ist eine Eigenschaft einer bestimmten Pininstanz auf dem Filter. Anforderungen für diese Eigenschaften geben Pinhandles an, geben aber keine Knoten-IDs an.
Knoteneigenschaften
Eine Knoteneigenschaft ist eine Eigenschaft eines Topologieknotens innerhalb des Filters. Eine Anforderung für eine Knoteneigenschaft gibt einen Filter-Handle oder einen Pin-Handle sowie eine Knoten-ID an.
Ob eine Knoteigenschaftsanfrage einen Filter- oder Pin-Handle angibt, hängt davon ab, ob der Knoten dem Filter eindeutig zugeordnet ist. Weitere Informationen finden Sie im folgenden Abschnitt "Node Properties".
Die folgende Abbildung zeigt die folgenden drei Arten von Eigenschaftsanforderungen: eine an eine Pin-Eigenschaftsinstanz gesendete Pin-Eigenschaftsanforderung, eine an einen Knoten gesendete Knotenanforderung (in einem Filter- oder Pininstanz) und eine an eine Filterinstanz gesendete Filtereigenschaftsanforderung.
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 eingebaute Handler für die Filter- und Pineigenschaften bereit, die vom SysAudio-Systemtreiber (siehe KSPROPSETID_Sysaudio und KSPROPSETID_Sysaudio_Pin) und dem WDMAud-Systemtreiber verwendet werden. Ein Miniporttreiber muss keine Handler für Eigenschaften implementieren, die der Porttreiber behandelt. Ein typischer Miniporttreiber bietet nur wenige Handler für Filter- und Pineigenschaften, wenn überhaupt. Der Miniporttreiber stellt die Handler für Knoteneigenschaften bereit, die hardwareabhängige Features des Audiogeräts darstellen. Die Porttreiber liefern 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 einen eigenen Handler und ignoriert den Miniporttreiberhandler.
Filterdeskriptoren
Der Porttreiber ruft Zeiger auf die Eigenschaftenhandler des Miniporttreibers ab, indem die IMiniport::GetDescription-Methode aufgerufen wird. Mit dieser Methode ruft der Porttreiber einen Zeiger auf den Filterdeskriptor des Miniporttreibers ab, der eine Struktur vom Typ PCFILTER_DESCRIPTOR ist. Diese Struktur spezifiziert die Eigenschaftsbehandler des Miniporttreibers für Filter-, Pin- und Knoteneigenschaften.
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 Eigenschafts-Handler für die Pin-Eigenschaften eines bestimmten Pin-Typs 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 Filtereigenschaftshandler des Miniporttreibers zu. In der Regel enthält diese Automatisierungstabelle nur wenige Handler, da der Porttreiber eigene, integrierte 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 in den Miniport-Treiberimplementierungen im Sysvad-Beispieltreiber, der in Beispielaudiotreibern erläutert wird.
Alle Porttreiber in Portcls.sys stellen die Behandlung für die KSPROPSETID_Pin und KSPROPSETID_Topology-Eigenschaftssätze bereit. Alle Eigenschaften in diesen Sätzen sind Filtereigenschaften, mit Ausnahme von KSPROPERTY_TOPOLOGY_NAME, eine Knoteneigenschaft (die ein Filterhandle verwendet, kein Pinhandle, 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 enthalten Informationen zu den Pin-Fabriken, die zu einem Filter gehören. In der Regel fragen Klienten 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, bei der es sich um eine get-only-Eigenschaft eines DirectMusic-Filters handelt. KSPROPERTY_SYNTH_MASTERCLOCK ist ein Element des KSPROPSETID_SynthClock Eigenschaftensatzes.
Pin-Eigenschaften
Der Porttreiber greift über das Pins-Mitglied von PCFILTER_DESCRIPTOR auf die Pin-Eigenschaftshandler des Miniporttreibers zu. Dieses Element verweist auf ein Array von Pindeskriptoren, und jeder Deskriptor verweist auf die Automatisierungstabelle für einen Pintyp (identifiziert durch eine Pin-ID, die einfach der Arrayindex ist).
In der Regel enthalten diese Automatisierungstabellen nur wenige Einträge, da der Porttreiber eigene Handler für alle Pineigenschaften bereitstellt, die SysAudio und WDMAud verwenden. Ein Miniporttreiber hat die Möglichkeit, Handler für eine oder mehrere Pin-Eigenschaften bereitzustellen, die der Porttreiber nicht behandelt, aber nur Clients, die mit diesen Eigenschaften vertraut sind, können Anfragen für diese 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 ein IRP empfängt, das eine Anforderung für eine dieser Eigenschaften enthält, wird das IRP nicht an den Miniporttreiber übergeben. Stattdessen verarbeitet der Porttreiber die Anforderung selbst, aber der Handler ruft die benötigten Informationen durch Aufrufen eines Einstiegspunkts im Miniporttreiber ab. Beispielsweise stellt der Porttreiber einen eigenen Eigenschaftshandler für KSPROPERTY_AUDIO_POSITION Anfragen bereit. Dieser Handler ruft einfach die GetPosition-Methode des Miniporttreiberdatenstroms auf (z. B. IMiniportWavePciStream::GetPosition), um die aktuelle Position abzurufen.
Knoteneigenschaften
Der Porttreiber greift über das Knotenelement von PCFILTER_DESCRIPTOR auf die Knoteneigenschaften-Handler des Miniporttreibers zu. Dieses Element verweist auf ein Array von Knotendeskriptoren, und jeder Deskriptor verweist auf die Automatisierungstabelle für einen Knotentyp (identifiziert durch eine Knoten-ID, die einfach der Arrayindex ist). In der Regel befinden sich alle oder die meisten Eigenschaftenhandler, die zu einem Miniporttreiber gehören, im Nodes-Array. Ein Audiotreiber stellt die Hardwaresteuerelemente in einem Audiogerät als Topologieknoten dar und verwendet den Eigenschaftenmechanismus, um Clients Zugriff auf die hardwareabhängigen Steuerelementeinstellungen zu ermöglichen.
Wie bereits beschrieben, sendet ein Client eine Filtereigenschaftsanforderung an ein Filterhandle und eine Pin-Eigenschaftsanforderung an einen Pinhandle. Im Gegensatz zu einer Filter- oder Pininstanz ist ein Knoten kein Kernelobjekt und verfügt nicht über ein Handle. Ein Client sendet eine Knoteneigenschaftsanforderung entweder an ein Pinhandle oder ein Filterhandle. Die Anforderung gibt jedoch eine Knoten-ID an, um zu kennzeichnen, dass die Anforderung für eine Knoteneigenschaft und nicht für eine Pin- oder Filtereigenschaft ist.
Im Folgenden finden Sie allgemeine Regeln, um festzustellen, 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 jede Pininstanz eine Instanz des Knotens. In diesem Fall muss eine Anforderung einer Knoteneigenschaft ein Pin-Handle (und nicht nur ein Filter-Handle) angeben, um zwischen mehreren Instanzen von demselben Knotentyp zu unterscheiden. Die Kombination aus Pinhandle und Knoten-ID identifiziert eindeutig eine bestimmte Knoteninstanz als Ziel für die Anforderung.
Wenn ein Filter nur eine Instanz 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 Audio Drivers Property Sets verweisen, um zu überprüfen, ob das Ziel für die Eigenschaft als Filterhandle oder Pinhandle angegeben werden soll.
Die Porttreiber in Portcls.sys bieten derzeit keine integrierte Behandlung von Knoteneigenschaften, mit Ausnahme von KSPROPERTY_TOPOLOGY_NAME.
Über- und Unter-spezifizierte Eigenschaftsanfragen
Fahrer sollten darauf vorbereitet sein, Anfragen zu Eigenschaften von Kunden zu behandeln, die nicht den vorangegangenen Regeln entsprechen. Anforderungen können entweder überspezifiziert oder nicht angegeben werden:
Überspezifische Anforderungen
Wenn für eine Eigenschaftsanforderung nur ein Filterhandle erforderlich ist, aber der Client die Anforderung stattdessen an ein Pinhandle sendet, wird das Ziel für die Anforderung überspezifiziert. 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 wurde, der die Pin enthält.
Unzureichend spezifizierte Anfragen
Wenn für eine Eigenschaftsanforderung ein Pin-Handle erforderlich ist, der Client die Anforderung jedoch stattdessen an ein Filter-Handle sendet, ist das Ziel für die Anforderung unpräzise spezifiziert. Wenn ein Filter beispielsweise mehrere Pininstanzen mit demselben Knotentyp enthält und ein Client eine Anforderung für eine Eigenschaft dieses Knotentyps an ein Filterhandle und nicht an ein Pinhandle sendet, hat der Treiber keine Möglichkeit, zu bestimmen, welche Knoteninstanz die Anforderung empfangen soll. In diesem Fall hängt das Verhalten vom Treiber ab. Anstatt alle unvollständig angegebenen Anforderungen automatisch abzulehnen, behandeln einige Treiber eine unvollständig angegebene Setzeigenschaftsanforderung als gültig. In diesem Fall ist die Interpretation, dass die Anforderung den Standardwert für die angegebene Knoten-ID festlegt. Wenn eine Pinfactory eine neue Knoteninstanz erstellt, wird die Eigenschaft, die zum neuen Knoten gehört, mit dem Standardwert initialisiert. Eine Anforderung, die den Standardwert ändert, wirkt sich nicht auf Knoteninstanzen aus, die vor der Anforderung erstellt wurden. Darüber hinaus schlagen Treiber durchweg bei unzureichend spezifizierten Get-Property-Anfragen fehl, da der Handler keine Möglichkeit hat, zu bestimmen, welche Knoteninstanz nach der Eigenschaft abgefragt werden soll.
Ausnahmen von den Regeln
Aus historischen Gründen weisen einige Audioeigenschaften verhaltensbedingte Eigenheiten auf, die gegen diese allgemeinen Regeln verstoßen. Es folgen Beispiele:
Wie unter Anwenden von Speaker-Configuration-Einstellungen beschrieben, kann ein Client die Lautsprecherkonfiguration eines Audiogeräts ändern, indem die KSPROPERTY_AUDIO_CHANNEL_CONFIG Eigenschaft eines 3D-Knotens (KSNODETYPE_3D_EFFECTS) festgelegt wird. Die Einstellung für die Lautsprecherkonfiguration ist global, da sie die Lautsprecherkonfiguration für alle Audio-Ströme ändert, die Teil des Mixes sind, den das Gerät über die Lautsprecher ausgibt. Gemäß der allgemeinen Regel sollte eine Knoteneigenschaftsanforderung, die sich auf den Filter als Ganzes auswirkt, ein Filterhandle (plus eine Knoten-ID) angeben. Für diese bestimmte Eigenschaft ist jedoch ein Pin-Griff anstelle eines Filtergriffs erforderlich. Der Pinhandle legt die Pininstanz fest, die den 3D-Knoten enthält, der das Ziel für die Anforderung ist.
KSPROPERTY_SYNTH_VOLUME und KSPROPERTY_SYNTH_MASTERCLOCK sind Eigenschaften eines Synth-Knotens (KSNODETYPE_SYNTHESIZER). Obwohl beide Knoteneigenschaften sind, enthalten Anforderungen für diese Eigenschaften keine Knoten-IDs. (Beachten Sie, dass der Eigenschaftsdeskriptor 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 das Nodes-Element von PCFILTER_DESCRIPTOR (anstelle des Pins-Members ) bereitstellen.