07.02.21
Inhaltsverzeichnis
- Einführung
- Zugriff auf die Schnittstelle
- Schnittstellenmemberfunktionen
- DWORD iA4APrivateGetVersion()
- ungültig iA4APrivateEnumerate()
- void iA4APrivateEnumSetCallback(BOOL (void *), void * pCbData)
- A4AError iA4APrivateGetDeviceProperty (A4ADeviceProperty Geräteeigenschaft, langer Geräteindex, void *PropertyData, lange Datengröße)
- A4AError iA4APrivateSetDeviceProperty (A4ADeviceProperty Geräteeigenschaft, langer Geräteindex, void *PropertyData, lange Datengröße)
- A4AError iA4APrivateGetInterfaceProperty (A4AInterfaceProperty Schnittstelleneigenschaft, langer Geräteindex, langer Schnittstellenindex, void *PropertyData, lange Datengröße)
- A4AError iA4APrivateSetInterfaceProperty(A4AInterfaceProperty Schnittstelleneigenschaft, langer Geräteindex, langer Schnittstellenindex, void *PropertyData, lange Datengröße)
- A4AError iA4APrivateGetPinProperty (A4APinProperty PinProperty, langer Geräteindex, langer Schnittstellenindex, langer PinIndex, void *PropertyData, lange Datengröße)
- A4AError iA4APrivateSetPinProperty (A4APinProperty PinProperty, langer Geräteindex, langer Schnittstellenindex, langer PinIndex, void *PropertyData, lange Datengröße)
- Fehlercodes
- Beispielanwendung
- Referenzen
Einführung
Der ASIO4ALL-Treiber stellt der Host-Anwendung eine Standard-ASIO-Schnittstelle zur Verfügung, mit der der Host bestimmte Aspekte des Treiberverhaltens steuern kann. Andere Aspekte, wie die WDM-Gerätekonfiguration, werden von den Steuerungsmöglichkeiten einer Standard-ASIO-Schnittstelle nicht abgedeckt. Mit dem Bedarf nach mehr Kontrolle im Hinterkopf – einschließlich der Möglichkeit für den OEM, einen eigenen Ersatz für die ursprüngliche ASIO4ALL-GUI bereitzustellen – wurde eine proprietäre Schnittstelle zur ASIO4ALL-Core-Engine erstellt.
Der Geltungsbereich dieser Schnittstellendefinition gilt für alle 2.x-Versionen der kostenlos verfügbaren ASIO4ALL-Software ab Version 2.9 sowie für benutzerdefinierte Builds, für die die Unterstützung dieser Schnittstelle spezifiziert wurde.
Zugriff auf die Schnittstelle
Da auf ASIO unter Windows als COM-In-Process-Serverobjekt zugegriffen wird, lag die naheliegende Designentscheidung darin, denselben Mechanismustyp auch für die proprietäre Schnittstelle zu verwenden.
Eine selbstregistrierende Treiber-DLL, die die private ASIO4ALL-Schnittstelle unterstützt, registriert diese zusammen mit der Standard-ASIO-Schnittstelle in ihrer DLLRegisterServer-Routine. Anwendungsentwickler können jedes vorhandene IASIO nach einem IA4APRIVATE abfragen und, sobald es gefunden wurde, die bereitgestellte Funktionalität nutzen.
Folglich ist das Erstellen einer Instanz der privaten ASIO4ALL-Schnittstelle so einfach wie:
CoCreateInstance(IID_IASIO,0,1,IID_IA4APRIVATE, (LPVOID*) &ifcInstance);
- siehe den Konstruktorcode der Wrapperklasse a4aInterface.cpp!
Die Schnittstellen-CLSID (in CLSID.cpp) ist {A26078C5-2840-4726-B427-E60FC8FEE403}.
Die eigentliche Definition der Schnittstelle sowie alle zugehörigen Deklarationen finden Sie in COMMON\iaa4aprv.h
Schnittstellenmemberfunktionen
DWORD iA4APrivateGetVersion()
Diese Funktion kann jederzeit aufgerufen werden und gibt die Version der privaten Schnittstelle in der BCD-codierten Form 0xMMMMmmmm zurück, wobei MMMM die Haupt- und mmmm die Nebenrevisionsnummer ist. Revision 1.23 würde als 0x00010023 codiert.
ungültig iA4APrivateEnumerate()
Der Aufruf dieser Funktion führt dazu, dass der Treiber die Enumeration der Audiogeräte erneut ausführt. Der Aufruf ist nur dann sicher, wenn sich der Treiber im Leerlaufzustand befindet („initialisiert“ gemäß ASIO-Spezifikation). Diese Funktion wird normalerweise verwendet, nachdem ein Rückruf installiert wurde, da der Rückruf unmittelbar nach der Enumeration aufgerufen wird, sodass die Anwendung die Kontrolle über die WDM-Gerätekonfiguration übernehmen kann.
void iA4APrivateEnumSetCallback(BOOL (void *), void * pCbData)
Installiert einen Callback, den der Treiber unmittelbar nach der Enumeration des Audiogeräts aufruft. Das Argument pCbData ist ein Zeiger auf beliebige Daten und wird an die Callback-Funktion übergeben. Normalerweise würde dies auf Instanzdaten usw. zeigen. Der Callback wird immer aufgerufen, nachdem der Treiber seine interne WDM-Geräte-(Neu-)Enumeration abgeschlossen hat. Verwenden Sie iA4APrivateEnumerate(), damit der Treiber die Enumeration sofort erneut ausführt!
Wenn die Callback-Funktion TRUE zurückgibt, führt der Treiber die Enumeration noch einmal aus. Normalerweise sollten Sie also FALSE zurückgeben, um Endlosschleifen zu vermeiden!
Nur im Rahmen der Callback-Funktion ist der Zugriff auf Audiogeräte-/Schnittstellen-/Pin-Eigenschaften sicher! Zugriffe auf diese Eigenschaften außerhalb des Callbacks können zu unvorhersehbaren Ergebnissen führen!
A4AError iA4APrivateGetDeviceProperty (A4ADeviceProperty Geräteeigenschaft, langer Geräteindex, void *PropertyData, lange Datengröße)
Liest die Eigenschaft DeviceProperty des aufgezählten Audiogeräts DeviceIndex in den vom Benutzer bereitgestellten Speicher PropertyData der Größe DataSize.
Kann nur im Rahmen eines Enumerations-Callbacks sicher verwendet werden!
A4AError iA4APrivateSetDeviceProperty (A4ADeviceProperty Geräteeigenschaft, langer Geräteindex, void *PropertyData, lange Datengröße)
Schreibt die Eigenschaft DeviceProperty des aufgezählten Audiogeräts DeviceIndex aus dem vom Benutzer bereitgestellten Speicher PropertyData der Größe DataSize.
Kann nur im Rahmen eines Enumerations-Callbacks sicher verwendet werden!
DeviceProperty kann eines der folgenden sein:
kA4A_Device_dwFlags [Datengröße=4]
Dies ist ein Bitfeld mit den folgenden Bitdefinitionen:
| A4A_FLAG_HWBUFFER | Aktivieren Sie die Hardware-Pufferzugriffsmethode. |
| A4A_FLAG_FORCESRC | Erzwingen Sie eine Neuabtastung von 44.1<-> 48 kHz |
| A4A_FLAG_PULLMODE | Erlauben Sie den „Pull“-Modus für WaveRT-Geräte, falls unterstützt. |
| A4A_FLAG_FORCE16 | Begrenzen Sie die Bittiefe der WDM-Schnittstelle auf 16 |
| A4A_FLAG_LÄUFT | Zeigt an, dass sich das Objekt im Status „Läuft“ befindet. |
| A4A_FLAG_FEHLER | Nicht angegebener Fehlerindikator. |
| A4A_FLAG_AKTIVIERT | In der aktuellen Konfiguration aktiviert. |
kA4A_Device_lpszName [Datengröße=sizeof(void*)]
Zeiger auf die Gerätenamenzeichenfolge (wie aus der Registrierung abgerufen)
kA4A_Device_lpszVendorName [Datengröße=sizeof(void*)]
Zeiger auf die Zeichenfolge mit dem Herstellernamen (wie aus der Registrierung abgerufen)
kA4A_Device_lpszServiceName [Datengröße=sizeof(void*)]
Zeiger auf die Zeichenfolge mit dem Dienstnamen (wie aus der Registrierung abgerufen)
kA4A_Device_lpszLocationInfo [Datengröße=sizeof(void*)]
Zeiger auf die Standortinformationszeichenfolge (wie aus der Registrierung abgerufen)
kA4A_Device_lpszDeviceID [Datengröße=sizeof(void*)]
Zeiger auf PnP-ID-Zeichenfolge (wie aus der Registrierung abgerufen)
kA4A_Device_dwBusNumber [Datengröße=4]
Busnummer (wie aus der Registrierung abgerufen). Tatsächlich eine 3-stellige Zeichenfolge mit abschließender 0.
kA4A_Device_dwKsBuffers [Datengröße=4]
Anzahl der zu verwendenden Kernel-Puffer.
kA4A_Device_dwIoDelay [Datengröße=4]
Verzögerungsoffset im Hardware-Puffer (ms).
kA4A_Device_dwInputComp [Datengröße=4]
Kompensation der Eingangslatenz (Beispiele)
kA4A_Device_dwOutputComp [Datengröße=4]
Kompensation der Ausgabelatenz (Samples)
kA4A_Device_dwBufferSize [Datengröße=4]
ASIO-Puffergröße (Samples) für dieses Gerät.
A4AError iA4APrivateGetInterfaceProperty (A4AInterfaceProperty Schnittstelleneigenschaft, langer Geräteindex, langer Schnittstellenindex, void *PropertyData, lange Datengröße)
Liest die Eigenschaft „InterfaceProperty“ der aufgezählten Geräteschnittstelle „InterfaceIndex“ auf dem aufgezählten Audiogerät „DeviceIndex“ in den vom Benutzer bereitgestellten Speicher „PropertyData“ der Größe „DataSize“.
Kann nur im Rahmen eines Enumerations-Callbacks sicher verwendet werden!
A4AError iA4APrivateSetInterfaceProperty(A4AInterfaceProperty Schnittstelleneigenschaft, langer Geräteindex, langer Schnittstellenindex, void *PropertyData, lange Datengröße)
Schreibt die Eigenschaft „InterfaceProperty“ der aufgezählten Geräteschnittstelle „InterfaceIndex“ auf das aufgezählte Audiogerät „DeviceIndex“ aus dem vom Benutzer bereitgestellten Speicher „PropertyData“ der Größe „DataSize“.
Kann nur im Rahmen eines Enumerations-Callbacks sicher verwendet werden!
Schnittstelleneigenschaftkann eines der folgenden sein:
kA4A_Interface_dwFlags [Datengröße=4]
Dies ist ein Bitfeld mit den folgenden Bitdefinitionen:
| A4A_FLAG_RTAUDIO | Zeigt an, dass es sich bei der Schnittstelle um WaveRT handelt. |
| A4A_FLAG_LÄUFT | Zeigt an, dass sich das Objekt im Status „Läuft“ befindet. |
| A4A_FLAG_FEHLER | Nicht angegebener Fehlerindikator. |
| A4A_FLAG_AKTIVIERT | In der aktuellen Konfiguration aktiviert. |
kA4A_Interface_lpszName [Datengröße=sizeof(void*)]
Zeichenfolge des Schnittstellennamens, wie aus der Registrierung abgerufen.
kA4A_Interface_pSPDIDD [Datengröße=sizeof(void*)]
Zeiger auf die SP_DEVICE_INTERFACE_DETAIL_DATA-Struktur für diese Geräteschnittstelle, siehe Windows DDK für die Strukturdefinition!
kA4A_Interface_dwProperties [Datengröße=4]
Physikalische Eigenschaften der Geräteschnittstelle. Kann eines der folgenden sein:
- A4A_IFPROPERTY_ADC
- A4A_IFPROPERTY_DAC
- A4A_IFPROPERTY_SPDIF
A4AError iA4APrivateGetPinProperty (A4APinProperty PinProperty, langer Geräteindex, langer Schnittstellenindex, langer PinIndex, void *PropertyData, lange Datengröße)
Liest die Eigenschaft PinProperty des Audio-Pins PinIndex an der aufgezählten Geräteschnittstelle InterfaceIndex am aufgezählten Audiogerät DeviceIndex in den vom Benutzer bereitgestellten Speicher PropertyData der Größe DataSize.
Kann nur im Rahmen eines Enumerations-Callbacks sicher verwendet werden!
A4AError iA4APrivateSetPinProperty (A4APinProperty PinProperty, langer Geräteindex, langer Schnittstellenindex, langer PinIndex, void *PropertyData, lange Datengröße)
Schreibt die Eigenschaft PinProperty des Audio-Pins PinIndex auf die aufgezählte Geräteschnittstelle InterfaceIndex auf das aufgezählte Audiogerät DeviceIndex aus vom Benutzer bereitgestellten Speicher PropertyData der Größe DataSize.
Kann nur im Rahmen eines Enumerations-Callbacks sicher verwendet werden!
Pin-Eigenschaftkann eines der folgenden sein:
kA4A_Pin_dwFlags [Datengröße=4]
Dies ist ein Bitfeld mit den folgenden Bitdefinitionen:
| A4A_FLAG_VERFÜGBAR | Mindestens eine mögliche Instanz bleibt übrig. |
| A4A_FLAG_LÄUFT | Zeigt an, dass sich das Objekt im Status „Läuft“ befindet. |
| A4A_FLAG_FEHLER | Nicht angegebener Fehlerindikator. |
| A4A_FLAG_AKTIVIERT | In der aktuellen Konfiguration aktiviert. |
kA4A_Pin_dwDataFlow [DataSize=4]
Mögliche Werte:
- KSPIN_DATAFLOW_IN (für „Ausgabepin“)
- KSPIN_DATAFLOW_OUT (für „Eingabepin“)
– Definitionen finden Sie im Windows DDK!
kA4A_Pin_dwMaxChannels [DataSize=4]
Maximale PCM-Kanäle.
kA4A_Pin_dwMaxBits [DataSize=4]
Maximale Audio-Bittiefe.
kA4A_Pin_dwMinSR [Datengröße=4]
Minimale Abtastfrequenz (Hz).
kA4A_Pin_dwMaxSR [Datengröße=4]
Maximale Abtastfrequenz (Hz).
Fehlercodes
Funktionen, die den Typ A4AError zurückgeben, geben eines der folgenden Ergebnisse zurück:
A4A_PRIVATE_NOERROR
Der Vorgang wurde erfolgreich abgeschlossen.
A4A_PRIVATE_ERR_ENUM_REENTRY
Es wurde versucht, die Geräteaufzählung erneut zu starten, während die Geräteaufzählung bereits läuft. Der wahrscheinlichste Grund ist ein mit iA4APrivateEnumSetCallback() installierter Rückruf, der versucht, iA4APrivateEnumerate() aufzurufen. iA4APrivateEnumerate() darf niemals innerhalb des Rückrufs verwendet werden!
A4A_PRIVATE_ERR_DRIVER_NOT_IDLE
Es wurde versucht, auf Enumerationsdaten zuzugreifen, während sich der ASIO-Treiber nicht im Leerlaufzustand befindet. Stoppen Sie alle Audioverarbeitungen und rufen Sie erst dann iA4APrivateEnumerate() auf!
A4A_PRIVATE_ERR_KEIN_SOLCHES_OBJEKT
Das Objekt (Gerät, Schnittstelle, Pin) mit dem angegebenen Index existiert nicht. Dieser Fehler kann beim Aufzählen von Objekten auftreten. Wenn dieser Code innerhalb einer Aufzählungsschleife zurückgegeben wird, ist dies ein Hinweis darauf, dass das Ende der Geräte-/Schnittstellen-/Pinliste erreicht wurde.
A4A_PRIVATE_ERR_ILLEGAL_ARGUMENT
An die Schnittstelle wurde ein Argument übergeben, das außerhalb des von ihr verarbeiteten Bereichs liegt. Mögliche Ursachen sind außerhalb des gültigen Bereichs liegende Eigenschaftskennungen, ein NULL-Zeiger auf Eigenschaftsdaten oder ein zu kleines Datengrößenargument für die angeforderte Eigenschaft.
Beispielanwendung
Es wird ein MSVC++-Beispielanwendungsprojekt bereitgestellt, das die Verwendung der in diesem Dokument beschriebenen API zur Verwaltung der WDM-Gerätekonfiguration im Kontext Ihrer Anwendung demonstriert.
Referenzen
- ASIO SDK, Steinberg Media Technologies GmbH
- Windows-Treiberkit, Microsoft, Corp.
- Win32 Software Development Kit, Microsoft, Corp.
- ASIO4ALL Bedienungsanleitung, Michael Tippach
Copyright © 2003-2021, Michael Tippach
Sofern nicht anders vereinbart, wird keine Gewährleistung für die Richtigkeit der in diesem Dokument bereitgestellten Informationen und für zukünftige Änderungen der hierin beschriebenen Schnittstellen und Definitionen übernommen.
Alle hierin verwendeten Warenzeichen sind das uneingeschränkte Eigentum ihrer jeweiligen Inhaber und werden nur zu Zwecken der Produktidentifikation verwendet.
