Zusammenfassung von ACX-Objekten
Dieses Thema enthält eine allgemeine Zusammenfassung von ACX-Objekten (Audio Class Extensions), die die Basis eines ACX-Audiotreibers bilden. Eine allgemeine Übersicht über ACX finden Sie in der Übersicht über ACX-Audioklassenerweiterungen.
ACX-Objekte sind Windows Driver Framework-Objekte (WDF) – WDFOBJECT. Weitere Informationen zu WDF finden Sie in Einführung in Framework-Objekte. Eine Zusammenfassung der WDF-Objekte finden Sie in Zusammenfassung von Framework-Objekten.
Hinweis
Die ACX-Header und -Bibliotheken sind nicht im WDK 10.0.22621.2428 (veröffentlicht am 24. Oktober 2023) enthalten, sind aber in früheren Versionen sowie in der neuesten Insider-Vorschauversion (Builds der 25000er-Serie) des WDK verfügbar. Weitere Informationen zu Vorschauversionen des WDK finden Sie unter Installieren von Vorschauversionen des Windows Driver Kit (WDK).
ACX-Objekthierarchie
In ACX (wie in WDF) ist das Treiberobjekt das Stammobjekt, und alle anderen Objekte sind untergeordnete Objekte/Nachfolger. Alle ACX-Objekte sind direkt oder indirekt über andere ACX- oder WDF-Objekte untergeordnete Elemente des Treiberobjekts. Ein ACX-Treiber kann das übergeordnete Element eines ACX-Objekts während der Erstellungszeit angeben. Wenn das übergeordnete Element nicht angegeben ist, verwendet ACX ein übergeordnetes Standardelement, wie in diesen Abschnitten beschrieben.
ACX-Verbindung
Ein AcxCircuit stellt einen teilweisen oder vollständigen Audiopfad zu einem vom Benutzer wahrgenommenen Audiogerät dar (Lautsprecher, Mikrofon usw.). Ein AcxCircuit verfügt über mindestens einen Eingabe-Pin und einen Ausgabe-Pin (ACXPIN), und er kann ein oder mehrere AcxElements-ähnliche Objekte aggregieren. Standardmäßig werden AcxElements in derselben Assemblyreihenfolge „verbunden“.
Die Audioverbindung ist der Grundbaustein von ACX. Im neuen ACX-Framework erstellt ein Audiotreiber ein oder mehrere ACX-Verbindungsobjekte, um einen teilweisen oder vollständigen Audiodaten-/Steuerpfad darzustellen. ACX fasst diese ACX-Verbindungsobjekte zusammen, um einen vollständigen Audiopfad zu erstellen, der einen Audioendpunkt darstellt. ACX ist für die Verwaltung der ACX-Verbindungen und deren Abhängigkeiten verantwortlich. Die Reihenfolge, in der diese Verbindungen zusammengestellt werden, kann statisch zur Initialisierungszeit oder dynamisch zur Laufzeit definiert werden.
Ein Audioendpunkt in den ACX-Frameworks ist eine Sammlung von mindestens einer ACX-Verbindung. Jede ACX-Verbindung in einem Audiopfad mit mehreren Verbindungen muss zu einem anderen PnP-Gerätestapel gehören. Ein ACX-Treiber erstellt möglicherweise einen oder mehrere Verbindungen zur Initialisierungszeit oder zur Laufzeit als Nebeneffekt eines externen Ereignisses, z. B. nach der Erkennung einer neuen Audiokomponente oder da er sich bei ACX als Factory für einen bestimmten Verbindungstyp registriert hat, und das ACX-Framework forderte die Factory-Komponente auf, eine neue Verbindung dieses Typs zu erstellen (siehe ACX-Verbindungsmanager/-Factory weiter unten in diesem Thema).
Ein AcxCircuit kann einen oder mehrere Streams aufweisen.
Ein AcxCircuit verfügt über eine dedizierte WDF-Warteschlange. Weitere Informationen zu WDF-Warteschlangen finden Sie unter Framework-Warteschlangenobjekte.
Die DDIs für ACX-Verbindungen werden im Acxcircuit.h-Header beschrieben.
ACX Pin
Genau wie in WDM stellen Portcls-Audiotreiber und da AcxPin-Objekt die logischen Verbindungen (nicht physische Verbindungen) dar, über die Streams vom Systemkommunikationsbus in den Adapter oder vom Adapter in den Systemkommunikationsbus gelangen.
Die DDIs für den Pin werden im Acxpin.h-Header beschrieben.
ACX Stream
Ein AcxStream stellt einen Audiostream auf der Hardware einer bestimmten Verbindung dar. Ein AcxStream kann ein oder mehrere AcxElements-ähnliche Objekte aggregieren. Standardmäßig werden AcxElements in derselben Assemblyreihenfolge „verbunden“. Ein AcxStream ist nur einer ACX-Verbindung zugeordnet.
- Ein AcxStream verfügt über eine dedizierte WDF-Warteschlange. Weitere Informationen zu WDF-Warteschlangen finden Sie unter Framework-Warteschlangenobjekte.
- Ein AcxStream unterstützt unterschiedliche Zustände. Diese Zustände geben an, wann Audio fließt (RUN-Zustand) oder nicht fließt (PAUSE- oder STOP-Zustand).
- Derzeit unterstützt ACX zwei Arten von Streams: grundlegende ACX-Stream-Objekte, die von Nicht-Streaming-Verbindungen verwendet werden, und ACX-RT-Stream-Objekte, die von Streaming-Verbindungen verwendet werden.
Die DDIs für den Stream werden im acxstreams.h-Header definiert.
ACX-Ziele
WdfIoTarget ist eine WDF-Abstraktion, um die Kommunikation zwischen zwei verschiedenen Stapeln zu erleichtern. Weitere Informationen zu WDF-E/A-Zielen finden Sie in Einführung in E/A-Ziele.
- Treiber verwenden AcxTargetCircuit, um mit einer Remoteverbindung zu kommunizieren, die von einem anderen Stapel bereitgestellt wird. AcxTargetCircuit wird mithilfe eines WdfIoTarget implementiert.
- Treiber verwenden AcxTargetPin, um mit dem Pin einer Remoteverbindung zu kommunizieren, der von einem anderen Stack bereitgestellt wird. AcxTargetPin wird mithilfe eines WdfIoTarget implementiert, um Nachrichten an die Remote-Pin-Entität zu senden.
- Treiber verwenden AcxTargetElement, um mit dem Element einer Remoteverbindung zu kommunizieren, das von einem anderen Stapel bereitgestellt wird. AcxTargetElement wird mithilfe eines WdfIoTarget implementiert, um Nachrichten an die Remoteelemententität zu senden.
- Treiber verwenden AcxTargetStream, um mit dem Stream einer Remoteverbindung zu kommunizieren, der von einem anderen Stack bereitgestellt wird. AcxTargetStream wird mithilfe eines WdfIoTarget implementiert, um einen Remotestream zu erstellen und den Status des Remotestreams zu ändern.
- Treiber verwenden AcxTargetFactoryCircuit, um mit einer Remoteverbindungs-Factory-Instanz zu kommunizieren. AcxTargetFactoryCircuit wird mithilfe eines WdfTarget implementiert, um Nachrichten an die Remoteverbindungs-Factory zu senden.
Jeder der obigen ACX-Typen unterstützt Eigenschaften, Methoden und Ereignisse für die Interaktion mit der Remoteverbindung. Alle diese Typen basieren auf dem WdfIoTarget-Objekt.
Die DDIs für Ziele werden im acxtargets.h-Header definiert.
ACX Stream Bridge
Das AcxStreamBridge-Objekt wird von einer Verbindung verwendet, um eine Stream-Erstellung, Stream-Statusübergänge und DRM-Einstellungen zwischen Verbindungssegmenten zu verbreiten. Dieses Objekt wird nur in einem Szenario mit mehreren Verbindungen (Audio-Composite) verwendet. Ein Treiber kann einem Bridge-Pin ein oder mehrere ACXSTREAMBRIDGE-Objekte zuordnen. Ein Bridge-Pin ist der ACXPIN, der logisch mit dem entsprechenden ACXPIN in der anderen Verbindung verbunden ist.
Die DDIs für den Stream werden im acxstreams.h-Header beschrieben.
Beispiel für das Verbindungslayout des ACX-Audiomodulknotens
Das folgende Diagramm veranschaulicht eine ACX-Verbindung. Die Host- und Offload-Pins sind Eingänge der Schaltung mit einem Loopback-Pin, der zur Echounterdrückung verwendet werden könnte. Bei der Ausgabe kann es sich um einen Bridge-Pin, der an einen Lautsprecher weitergeleitet wird.
Beachten Sie, dass der Treiber den Schritt des expliziten Verbindens nicht ausführen muss, wenn Verbindungen/Elemente in derselben Reihenfolge verbunden werden, in der sie der Verbindung hinzugefügt wurden.
Standardmäßig verbindet ACX die Elemente beginnend mit dem ACX-Anforderungssenken-Pin der Verbindung und endend mit dem Geräte-Bridge-Pin der Verbindung für Render- und Erfassungsgeräte.
ACX-Manager
Der ACX-Manager wird für Systemaufgaben wie die Unterstützung zusammengesetzter Audioendpunkte verwendet. Diese Arten von Endpunkten werden von einem oder mehreren Treiber-Stacks desselben oder verschiedener Anbieter verwaltet. Clients können diese Konfiguration in ACPI vorab konfigurieren oder den DDI des ACX-Managers direkt verwenden. Die DDIs für den ACX-Manager werden im acxmanager.h-Header beschrieben.
ACX-Objektbehälter
Der ACX-Objektbehälter wird verwendet, um verschiedene Datentypen zu speichern. ACXOBJECTBAG kann als Argument in verschiedenen DDIs übergeben werden. Die DDIs für den Objektbehälter werden im Acxmisc.h-Header beschrieben.
ACX-Objektzusammenfassung
Die folgende Tabelle enthält alle ACX-Objekte und einige grundlegende Informationen zu den einzelnen Objekten.
| Handle | Name | Zweck |
|---|---|---|
| ACXMANAGER | Der ACX-Manager | Das ACX-Manager-Objekt, das zum Verwalten und Steuern anderer Objekte verwendet wird. |
| ACXOBJECTBAG | Objektbehälter | Wird zum Speichern von Daten für die Verwendung mit Objekten verwendet. |
| ACXEVENT | ACX-Ereignis | Für KS-Ereignisse (Kernelstreaming). |
| ACXEVENTDATA | Ereignisdaten | Die einem Ereignis zugeordneten Daten. |
| ACXPNPEVENT | Pnp-Ereignis | Für Plug & Play-Ereignisse. |
| ACXCIRCUIT | Leitung | Eine ACX-Verbindung, die oben in diesem Thema beschrieben wird. |
| ACXPIN | Anheften | Ein ACX-Pin-Objekt stellt die logischen Verbindungen dar und wird weiter oben in diesem Thema beschrieben. |
| ACXELEMENT | Element | Wird verwendet, um jedes Element darzustellen, das einem AcxCircuit oder AcxStream hinzugefügt werden kann, z. B. AcxVolume |
| ACXAUDIOENGINE | Audiomodul | Das ACX-Audiomodul, das in einer Renderverbindung verwendet wird, um einen DSP darzustellen. |
| ACXSTREAMAUDIOENGINE | Stream-Audiomodul | Wird in einem Renderdatenstrom verwendet, um einen DSP darzustellen. |
| ACXKEYWORDSPOTTER | Schlüsselworterkennung | Eine Schlüsselworterkennung, die in einer Erfassungsverbindung für die Schlüsselworterkennung in einem Audiostream verwendet wird. |
| ACXVOLUME | Volume | Wird verwendet, um Lautstärke, Erhöhung und Verstärkung darzustellen. |
| ACXMUTE | Mute | Wird verwendet, um ein Stummschaltungselement darzustellen. |
| ACXJACK | Jack | Wird verwendet, um eine Audiobuchse oder einen anderen physischen Konnektor darzustellen. |
| ACXMICARRAYGEOMETRY | Mikrofonarraygeometrie | Wird verwendet, um die Mikrofonarraygeometrie darzustellen, z. B. die Position der Mikrofone. |
| ACXPEAKMETER | Spitzenzähler | Wird verwendet, wenn die Hardware die Spitzenzähler-Funktionalität unterstützt. |
| ACXSTREAM | Stream | Wird verwendet, um einen von einer Verbindung erstellten Audiostream darzustellen, der oben in diesem Thema beschrieben wird. |
| ACXDATAFORMAT | Datenformat | Ein Datenformat stellt ein vom Audiogerät unterstütztes Datenformat dar. |
| ACXDATAFORMATLIST | Datenformatliste | Eine Liste der verfügbaren Audiodatenformate. |
| ACXTARGETCIRCUIT | Zielverbindung | Wird verwendet, um mit einer Remoteverbindung zu kommunizieren, die von einem anderen Stapel bereitgestellt wird. |
| ACXTARGETPIN | Ziel-Pin | Wird verwendet, um mit dem Pin einer Remoteverbindung zu kommunizieren, der von einem anderen Stapel bereitgestellt wird. |
| ACXTARGETELEMENT | Target-Element | Wird verwendet, um ein Zielelement darzustellen, das einem AcxCircuit oder AcxStream hinzugefügt werden kann, z. B. AcxVolume |
| ACXTARGETSTREAM | Zielstream | Wird verwendet, um mit dem Stream einer Remoteverbindung zu kommunizieren, der von einem anderen Stapel bereitgestellt wird. |
| ACXTARGETFACTORYCIRCUIT | Zielverbindungs-Factory | Wird für die Kommunikation mit der Factory einer Remoteverbindung verwendet. |
| ACXSTREAMBRIDGE | Stream Bridge | Wird von einer Verbindung verwendet, um eine Stream-Erstellung, Zustandsübergänge und DRM zwischen Verbindungselementen zu verbreiten. |
| ACXCOMPOSITE | Zusammengesetzt | Wird zur Darstellung von Stream-Architekturen mit mehreren Verbindungen, mehreren Stapeln und mehreren Anbietern verwendet. |
| ACXCOMPOSITEFACTORY | Composite Factory | Eine Factory, die zusammengesetzte Audioverbindungen erstellt. |
| ACXFACTORYCIRCUIT | Factory-Verbindung | Eine Factory, die Verbindungen mithilfe einer bestimmten Vorlage erstellt. |
| ACXCIRCUITMANAGER | Verbindungsmanager | Ein Verbindungsanbieter, der für die Erstellung dynamischer Verbindungen verwendet wird. |
| ACXCOMPOSITETEMPLATE | Zusammengesetzte Vorlage | Eine zusammengesetzte Vorlage stellt eine teilweise oder vollständige Audiobindung dar. Eine zusammengesetzte Vorlage kann eine oder mehrere Verbindungsvorlagen aufweisen. |
| ACXCIRCUITTEMPLATE | Verbindungsvorlage | Eine Verbindungsvorlage stellt einen partiellen Audiopfad dar. |
| ACXAUDIOMODULE | Audiomodul | Für benutzerdefinierte Drittanbieter-Funktionen hinzufügen. |
Die folgenden ACX-Objekte werden verwendet, um Verbindungs-, Stream- und Verbindungs-Factory-Informationen zu speichern.
| Handle | Zweck |
|---|---|
| ACXCIRCUIT_INIT | Speichert ACX-Verbindungsinitialisierungsdaten |
| ACXSTREAM_INIT | Speichert ACX-Streaminitialisierungsdaten |
| ACXFACTORYCIRCUIT_INIT | Speichert Initialisierungsdaten, die von einer ACX-Verbindungs-Factory verwendet werden |
Weitere Informationen
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