Audioeigenschaftenhandler
Ein Miniporttreiber speichert Informationen zu jeder unterstützten Eigenschaft in einer PCPROPERTY_ITEM-Struktur . Diese Struktur enthält die folgenden Informationen zur Eigenschaft:
Die Eigenschaftensatz-GUID und Eigenschafts-ID (oder Index)
Ein Funktionszeiger auf die Handlerroutine für die Eigenschaft
Flags, die die Vom Handler unterstützten Eigenschaftenvorgänge angeben
Der Miniporttreiber stellt eine Automatisierungstabelle (angegeben durch eine PCAUTOMATION_TABLE-Struktur ) für den Filter bereit. Der Treiber stellt zusätzliche Automatisierungstabellen für die Pin- und Knotentypen des Filters bereit. Jeder Pin- oder Knotentyp verfügt über eine eigene Tabelle. Jede Automatisierungstabelle enthält ein (möglicherweise leeres) Array von PCPROPERTY_ITEM Strukturen, und jede dieser Strukturen beschreibt eine Eigenschaft des Filters, Pins oder Knotens. Wenn ein Client eine Eigenschaftsanforderung an einen Filter, Pin oder Knoten sendet, leitet der Porttreiber die Anforderung über die Automatisierungstabelle an den entsprechenden Eigenschaftenhandler weiter.
Ein Miniporttreiber kann eine eindeutige Eigenschaftshandlerroutine für jede Eigenschaft angeben. Wenn ein Treiber jedoch mehrere ähnliche Eigenschaften verarbeitet, können diese manchmal zur Vereinfachung in einer einzelnen Handlerroutine konsolidiert werden. Ob sie einen eindeutigen Handler für jede Eigenschaft bereitstellen oder mehrere Eigenschaften in einem einzelnen Handler konsolidieren, ist eine Implementierungsentscheidung, die vom Treiberautor getroffen werden muss und für Clients transparent sein sollte, die Eigenschaftenanforderungen übermitteln.
Ein Benutzermodusclient kann eine Anforderung der Get-, Set- oder Basic-Support-Eigenschaft senden, indem die Microsoft Win32-Funktion DeviceIoControl aufgerufen wird, wobei der Aufrufparameter dwIoControlCode auf IOCTL_KS_PROPERTY festgelegt ist. Das Betriebssystem konvertiert diesen Aufruf in einen IRP, den es an den Klassentreiber sendet. Weitere Informationen finden Sie unter KS-Eigenschaften.
Wenn ein Client eine KS-Eigenschaftsanforderung (d. h. eine IOCTL_KS_PROPERTY I/O-Control-IRP) an einen Filterhandle oder Pinhandle sendet, übermittelt der KS-Systemtreiber (Ks.sys) die Anforderung an den Porttreiber für das Filterobjekt oder das Anheftobjekt. Wenn der Miniporttreiber einen Handler für die Eigenschaft bereitstellt, leitet der Porttreiber die Anforderung an den Handler weiter. Vor dem Weiterleiten der Anforderung konvertiert der Porttreiber die Informationen aus der Eigenschaftsanforderung in das von der PCPROPERTY_REQUEST-Struktur angegebene Format. Der Porttreiber übergibt diese Struktur an den Handler des Miniporttreibers.
Das MajorTarget-Element von PCPROPERTY_REQUEST auf die primäre Miniporttreiberschnittstelle für das Audiogerät verweist. Für ein WavePci-Gerät ist dies beispielsweise ein Zeiger auf die IMiniportWavePci-Schnittstelle des Miniporttreiberobjekts.
Im Fall einer KS-Eigenschaftsanforderung, die an ein Filterhandle gesendet wird, ist das MinorTarget-Element von PCPROPERTY_REQUEST NULL. Im Fall einer Anforderung, die an ein Pinhandle gesendet wird, zeigt MinorTarget auf die Streamschnittstelle für den Pin. Für ein WavePci-Gerät ist dies beispielsweise ein Zeiger auf die IMiniportWavePciStream-Schnittstelle des Streamobjekts.
Die Instance - und Value-Member von PCPROPERTY_REQUEST auf die Eingabe- bzw. Ausgabepuffer der KS-Eigenschaftsanforderung verweisen. (Die Puffer werden durch die Parameter lpInBuffer und lpOutBuffer der DeviceIoControl-Funktion angegeben.) Diese Puffer enthalten den Eigenschaftendeskriptor (instance Daten) bzw. den Eigenschaftswert (Vorgangsdaten), wie unter Eigenschaftensätze für Audiotreiber beschrieben. Das Value-Element zeigt auf den Anfang des Ausgabepuffers, aber der Instanzzeiger wird vom Anfang des Eingabepuffers versetzt.
Der Eingabepuffer beginnt entweder mit einer KSPROPERTY - oder KSNODEPROPERTY-Struktur . Der Porttreiber kopiert die Informationen aus dieser Struktur in die Member Node, PropertyItem und Verb der PCPROPERTY_REQUEST-Struktur. Wenn Daten der KSPROPERTY- oder KSNODEPROPERTY-Struktur im Puffer folgen, lädt der Porttreiber den Instanzmember mit einem Zeiger auf diese Daten. Andernfalls wird Instanz auf NULL festgelegt.
Wenn der Eingabepuffer mit einer KSPROPERTY-Struktur beginnt, die keine Knoteninformationen enthält, legt der Porttreiber das Knotenelement der PCPROPERTY_REQUEST Struktur auf ULONG(-1) fest. In diesem Fall ruft der Porttreiber den entsprechenden Handler aus der Automatisierungstabelle des Miniporttreibers für den Filter oder Pin auf, je nachdem, ob das Ziel für die Eigenschaftsanforderung durch einen Filterhandle oder einen Stifthandle angegeben wird. (Wenn die Tabelle keinen Handler für die -Eigenschaft angibt, verarbeitet der Porttreiber stattdessen die Anforderung.)
Wenn der Eingabepuffer mit einer KSNODEPROPERTY-Struktur beginnt, kopiert der Porttreiber die Knoten-ID aus dieser Struktur in den Knotenmember der PCPROPERTY_REQUEST-Struktur und ruft den entsprechenden Handler aus der Automatisierungstabelle des Miniporttreibers für den Knoten auf. (Wenn die Tabelle keinen Handler für die -Eigenschaft angibt, verarbeitet der Porttreiber stattdessen die Anforderung.)
Der Porttreiber überprüft das KSPROPERTY_TYPE_TOPOLOGY Bit in den Vorgangsflags der Eigenschaftsanforderung, um zu ermitteln, welche der beiden Strukturen KSPROPERTY oder KSNODEPROPERTY sich am Anfang des Eingabepuffers befindet:
Wenn dieses Bit festgelegt ist, ist die Anforderung für eine Knoteneigenschaft, und der Eingabepuffer beginnt mit einer KSNODEPROPERTY-Struktur.
Andernfalls beginnt der Eingabepuffer mit einer KSPROPERTY-Struktur.
Weitere Informationen zu KSPROPERTY_TYPE_TOPOLOGY finden Sie unter KSPROPERTY.
Die Member InstanceSize und ValueSize der PCPROPERTY_REQUEST Struktur geben die Größe der Puffer an, auf die die Member Instanz und Value verweisen. ValueSize entspricht der Größe des Ausgabepuffers der Eigenschaftsanforderung, aber InstanceSize ist die Größe der Daten, die der KSPROPERTY- oder KSNODEPROPERTY-Struktur im Eingabepuffer folgen. Das heißt, InstanceSize ist die Größe des Eingabepuffers abzüglich der Größe der KSPROPERTY- oder KSNODEPROPERTY-Struktur. Wenn dieser Struktur keine zusätzlichen Daten folgen, legt der Porttreiber InstanceSize auf Null (und Instance auf NULL) fest.
Wenn der Client beispielsweise eine KSNODEPROPERTY_AUDIO_CHANNEL-Struktur als instance Daten im Eingabepuffer angibt, übergibt der Porttreiber dem Handler eine PCPROPERTY_REQUEST Struktur, deren Instanzmitglied auf den Kanalmember der KSNODEPROPERTY_AUDIO_CHANNEL-Struktur verweist und dessen InstanceSize-Member den Wert enthält.
sizeof(KSNODEPROPERTY_AUDIO_CHANNEL) – sizeof(KSNODEPROPERTY)
Vor dem Übermitteln einer Get-Property-Anforderung zum Abrufen eines Eigenschaftswerts sollte der Client einen Ausgabepuffer zuweisen, in den der Eigenschaftenhandler des Miniporttreibers den Eigenschaftswert schreiben kann. Bei einigen Eigenschaften ist die Größe des Ausgabepuffers geräteabhängig, und der Client muss den Eigenschaftenhandler nach der erforderlichen Puffergröße abfragen. In diesen Fällen sendet der Client eine anfängliche Eigenschaftsanforderung mit einem Ausgabepufferzeiger von nullptr und einer Ausgabepufferlänge von 00. Der Handler antwortet, indem er die erforderliche Puffergröße zusammen mit dem status Code STATUS_BUFFER_OVERFLOW zurückgibt. Der Client ruft dann den Eigenschaftswert ab, indem er einen Ausgabepuffer der angegebenen Größe zuteilt und diesen Puffer in einer zweiten Get-Eigenschaftsanforderung sendet.
Wenn die angegebene Puffergröße zu klein ist, um eine der angeforderten Informationen zu empfangen, gibt die Methode STATUS_BUFFER_TOO_SMALL zurück.
In einigen Fällen geben PortCls-Porttreiber STATUS_BUFFER_TOO_SMALL anstelle von STATUS_BUFFER_OVERFLOW als Antwort auf eine Eigenschaftsanforderung mit einer Ausgabepufferadresse und -größe ohne Null zurück. Die erforderliche Puffergröße wird in solchen Fällen nicht zurückgegeben.
Weitere Informationen finden Sie unter Verwenden von NTSTATUS-Werten und diesen Blogbeiträgen: