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.
Ein Miniporttreiber speichert Informationen zu jeder Eigenschaft, die sie in einer PCPROPERTY_ITEM Struktur unterstützt. Diese Struktur enthält die folgenden Informationen zur Eigenschaft:
GuiD und Eigenschafts-ID (oder Index) des Eigenschaftensatzes
Ein Funktionszeiger auf die Handlerroutine für die Eigenschaft
Flags, die die vom Handler unterstützten Eigenschaftsvorgä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 Pintypen 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, des Pins oder des 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 aus Gründen der Bequemlichkeit in einer einzigen Handlerroutine fusioniert werden. Unabhängig davon, ob Sie einen eindeutigen Handler für jede Eigenschaft bereitstellen oder mehrere Eigenschaften in einem einzelnen Handler zusammenfassen möchten, ist eine Implementierungsentscheidung, die vom Treiberentwickler getroffen werden soll und für Clients, die Eigenschaftsanforderungen übermitteln, transparent sein sollte.
Ein Benutzermodus-Client kann eine Get-, Set- oder Basic-Support-Eigenschaftsanfrage senden, indem er die Microsoft Win32-Funktion DeviceIoControl aufruft und den Aufrufparameter „dwIoControlCode“ auf IOCTL_KS_PROPERTY festlegt. Das Betriebssystem konvertiert diesen Aufruf in ein IRP, das an den Klassentreiber verteilt wird. Weitere Informationen finden Sie unter KS Properties.
Wenn ein Client eine KS-Eigenschaftsanforderung (d. h. ein IOCTL_KS_PROPERTY I/O-Steuer-IRP) an einen Filterhandle oder Pinhandle sendet, liefert der KS-Systemtreiber (Ks.sys) die Anforderung an den Porttreiber für das Filterobjekt oder Pin-Objekt. Wenn der Miniporttreiber einen Handler für die Eigenschaft bereitstellt, wird die Anforderung vom Porttreiber an diesen Handler weitergeleitet. Vor dem Weiterleiten der Anforderung konvertiert der Porttreiber die Informationen aus der Eigenschaftsanforderung in das durch die PCPROPERTY_REQUEST Struktur angegebene Format. Der Porttreiber übergibt diese Struktur an den Miniporttreiberhandler.
Das MajorTarget-Element von PCPROPERTY_REQUEST verweist auf die primäre Miniporttreiberschnittstelle für das Audiogerät. Bei einem WavePci-Gerät ist dies beispielsweise ein Zeiger auf die IMiniportWavePci-Schnittstelle des Miniporttreiberobjekts .
Bei einer an ein Filterhandle gesendeten KS-Eigenschaftsanforderung ist das MinorTarget-Element von PCPROPERTY_REQUEST NULL. Bei einer Anforderung, die an einen Pinhandle gesendet wird, verweist MinorTarget auf die Datenstromschnittstelle für den Pin. Bei einem WavePci-Gerät ist dies beispielsweise ein Zeiger auf die IMiniportWavePciStream-Schnittstelle des Datenstromobjekts.
Die Elemente "Instance" und "Value" von PCPROPERTY_REQUEST zeigen auf die Eingabe- bzw. Ausgabepuffer der KS-Eigenschaftsanforderung. (Die Puffer werden durch die Parameter lpInBuffer und lpOutBuffer der DeviceIoControl-Funktion angegeben.) Diese Puffer enthalten den Eigenschaftsdeskriptor (Instanzdaten) und den Eigenschaftswert (Vorgangsdaten), wie in audio drivers Property Sets beschrieben. Der Wert-Member zeigt auf den Beginn des Ausgabebuffers, aber der Instanz-Zeiger ist vom Beginn des Eingabebuffers verschoben.
Der Eingabepuffer beginnt mit einer KSPROPERTY - oder KSNODEPROPERTY-Struktur . Der Porttreiber kopiert die Informationen aus dieser Datenstruktur in die Mitglieder "Node", "PropertyItem" und "Verb" der PCPROPERTY_REQUEST Datenstruktur. Wenn Daten der KSPROPERTY- oder KSNODEPROPERTY-Struktur im Puffer folgen, lädt der Porttreiber das Instance-Element 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 Node-Element der PCPROPERTY_REQUEST Struktur auf ULONG(-1) fest. In diesem Fall ruft der Porttreiber den entsprechenden Handler aus der Automatisierungstabelle des Miniport-Treibers für den Filter oder den Pin auf, abhängig davon, ob das Ziel der Eigenschaftsanfrage durch ein Filterhandle oder ein Pinhandle angegeben ist. (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 das Node-Element 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, behandelt der Porttreiber stattdessen die Anforderung.)
Der Porttreiber überprüft das KSPROPERTY_TYPE_TOPOLOGY Bit in den Vorgangsflags der Eigenschaftsanforderung, um zu bestimmen, welche der beiden Strukturen, KSPROPERTY oder KSNODEPROPERTY, am Anfang des Eingabepuffers gespeichert ist:
Wenn dieses Bit festgelegt ist, gilt 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ößen der Puffer an, auf die von den Membern "Instance " und "Value " verwiesen wird. 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 minus der Größe der KSPROPERTY- oder KSNODEPROPERTY-Struktur. Wenn keine zusätzlichen Daten dieser Struktur folgen, legt der Porttreiber InstanceSize auf Null (und Instance auf NULL) fest.
Wenn der Client z. B. eine KSNODEPROPERTY_AUDIO_CHANNEL Struktur als Instanzdaten im Eingabepuffer angibt, übergibt der Porttreiber den Handler eine PCPROPERTY_REQUEST Struktur, deren Instanzelement auf das Kanalelement 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 Eigenschaftshandler des Miniporttreibers den Eigenschaftswert schreiben kann. Bei einigen Eigenschaften ist die Größe des Ausgabepuffers geräteabhängig, und der Client muss den Eigenschaftenhandler für die erforderliche Puffergröße abfragen. In diesen Fällen sendet der Client eine anfängliche Eigenschaftsanforderung mit einem Ausgabepufferzeiger von nullptr und einer Ausgabepufferlänge von Null. Der Handler antwortet, indem die erforderliche Puffergröße zusammen mit dem Statuscode STATUS_BUFFER_OVERFLOW zurückgegeben wird. Der Client ruft dann den Eigenschaftswert ab, indem er einen Ausgabepuffer der angegebenen Größe zuteilt und diesen Puffer in einer zweiten Get-Property-Anforderung 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 Reaktion auf eine Eigenschaftsanfrage mit einer Nicht-Null-Ausgabepufferadresse und -größe 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: