IAudioClient::Initialize-Methode (audioclient.h)

Artikel
08/22/2023

Die Initialize-Methode initialisiert den Audiodatenstrom.

Syntax

HRESULT Initialize(
  [in] AUDCLNT_SHAREMODE  ShareMode,
  [in] DWORD              StreamFlags,
  [in] REFERENCE_TIME     hnsBufferDuration,
  [in] REFERENCE_TIME     hnsPeriodicity,
  [in] const WAVEFORMATEX *pFormat,
  [in] LPCGUID            AudioSessionGuid
);

Parameter

[in] ShareMode

Der Freigabemodus für die Verbindung. Über diesen Parameter teilt der Client der Audio-Engine mit, ob das Audioendpunktgerät für andere Clients freigegeben werden soll. Der Client sollte diesen Parameter auf einen der folgenden AUDCLNT_SHAREMODE-Enumerationswerte festlegen:

AUDCLNT_SHAREMODE_EXCLUSIVE

AUDCLNT_SHAREMODE_SHARED

[in] StreamFlags

Flags zum Steuern der Erstellung des Streams. Der Client sollte diesen Parameter auf 0 oder auf das bitweise OR einer oder mehrerer der AUDCLNT_STREAMFLAGS_XXX Konstanten oder der AUDCLNT_SESSIONFLAGS_XXX-Konstanten festlegen.

[in] hnsBufferDuration

Die Pufferkapazität als Zeitwert. Dieser Parameter ist vom Typ REFERENCE_TIME und wird in Einheiten von 100 Nanosekunden ausgedrückt. Dieser Parameter enthält die Puffergröße, die der Aufrufer für den Puffer anfordert, den die Audioanwendung mit der Audio-Engine (im freigegebenen Modus) oder mit dem Endpunktgerät (im exklusiven Modus) teilt. Wenn der Aufruf erfolgreich ist, ordnet die Methode einen Puffer zu, der mindestens so groß ist. Weitere Informationen zu REFERENCE_TIME finden Sie in der Windows SDK-Dokumentation. Weitere Informationen zu Pufferanforderungen finden Sie unter Hinweise.

[in] hnsPeriodicity

Der Gerätezeitraum. Dieser Parameter kann nur im exklusiven Modus ungleich 0 sein. Legen Sie im freigegebenen Modus diesen Parameter immer auf 0 fest. Im exklusiven Modus gibt dieser Parameter den angeforderten Planungszeitraum für aufeinander folgende Pufferzugriffe durch das Audioendpunktgerät an. Wenn der angeforderte Gerätezeitraum außerhalb des Bereichs liegt, der durch den Mindestzeitraum des Geräts und den maximalen Zeitraum des Systems festgelegt wird, klammert die Methode den Zeitraum auf diesen Bereich ein. Wenn dieser Parameter 0 ist, legt die Methode den Gerätezeitraum auf den Standardwert fest. Rufen Sie zum Abrufen des Standardgerätezeitraums die IAudioClient::GetDevicePeriod-Methode auf . Wenn das AUDCLNT_STREAMFLAGS_EVENTCALLBACK Streamflag festgelegt ist und AUDCLNT_SHAREMODE_EXCLUSIVE als ShareMode festgelegt ist, muss hnsPeriodicity ungleich null und gleich hnsBufferDuration sein.

[in] pFormat

Zeiger auf einen Formatdeskriptor. Dieser Parameter muss auf einen gültigen Formatdeskriptor vom Typ WAVEFORMATEX (oder WAVEFORMATEXTENSIBLE) verweisen. Weitere Informationen finden Sie in den Hinweisen.

[in] AudioSessionGuid

Zeiger auf eine Sitzungs-GUID. Dieser Parameter verweist auf einen GUID-Wert, der die Audiositzung identifiziert, zu der der Stream gehört. Wenn die GUID eine Sitzung identifiziert, die zuvor geöffnet wurde, fügt die -Methode den Stream zu dieser Sitzung hinzu. Wenn die GUID keine vorhandene Sitzung identifiziert, öffnet die -Methode eine neue Sitzung und fügt der Sitzung den Stream hinzu. Der Stream bleibt für seine Lebensdauer Mitglied derselben Sitzung. Das Festlegen dieses Parameters auf NULL entspricht der Übergabe eines Zeigers auf einen GUID_NULL Wert.

Rückgabewert

Wenn die Methode erfolgreich ist, wird S_OK zurückgegeben. Wenn ein Fehler auftritt, umfassen mögliche Rückgabecodes die in der folgenden Tabelle gezeigten Werte, sind jedoch nicht darauf beschränkt.

Rückgabecode	Beschreibung
AUDCLNT_E_ALREADY_INITIALIZED	Das IAudioClient-Objekt wurde bereits initialisiert.
AUDCLNT_E_WRONG_ENDPOINT_TYPE	Das AUDCLNT_STREAMFLAGS_LOOPBACK-Flag ist festgelegt, aber das Endpunktgerät ist ein Erfassungsgerät und kein Renderinggerät.
AUDCLNT_E_BUFFER_SIZE_NOT_ALIGNED	Hinweis Gilt für Windows 7 und höher. Die angeforderte Puffergröße ist nicht ausgerichtet. Dieser Code kann für ein Render- oder Aufnahmegerät zurückgegeben werden, wenn der Aufrufer AUDCLNT_SHAREMODE_EXCLUSIVE und die AUDCLNT_STREAMFLAGS_EVENTCALLBACK Flags angegeben hat. Der Aufrufer muss Initialize erneut mit der ausgerichteten Puffergröße aufrufen. Weitere Informationen finden Sie in den Hinweisen.
AUDCLNT_E_BUFFER_SIZE_ERROR	Hinweis Gilt für Windows 7 und höher. Gibt an, dass der von einem Client im exklusiven Modus angeforderte Wert für die Pufferdauer außerhalb des Bereichs liegt. Der angeforderte Dauerwert für den Pullmodus darf nicht größer als 5000 Millisekunden sein. für den Pushmodus darf der Wert für die Dauer nicht größer als 2 Sekunden sein.
AUDCLNT_E_CPUUSAGE_EXCEEDED	Gibt an, dass die Prozessdurchlaufdauer die maximale CPU-Auslastung überschritten hat. Die Audio-Engine verfolgt die CPU-Auslastung, indem die Anzahl der Überschreitet die Prozessdurchlaufdauer die maximale CPU-Auslastung beibehält. Die maximale CPU-Auslastung wird als Prozentsatz der Periodizität der Engine berechnet. Der Prozentwert ist der CPU-Drosselungswert des Systems (im Bereich von 10 % und 90 %). Wenn dieser Wert nicht gefunden wird, wird der Standardwert von 40 % verwendet, um die maximale CPU-Auslastung zu berechnen.
AUDCLNT_E_DEVICE_INVALIDATED	Das Audioendpunktgerät wurde nicht angeschlossen, oder die Audiohardware oder die zugehörigen Hardwareressourcen wurden neu konfiguriert, deaktiviert, entfernt oder anderweitig nicht mehr verfügbar gemacht.
AUDCLNT_E_DEVICE_IN_USE	Das Endpunktgerät wird bereits verwendet. Entweder wird das Gerät im exklusiven Modus verwendet, oder das Gerät wird im gemeinsamen Modus verwendet, und der Aufrufer wird aufgefordert, das Gerät im exklusiven Modus zu verwenden.
AUDCLNT_E_ENDPOINT_CREATE_FAILED	Die -Methode konnte den Audioendpunkt für das Render- oder Aufnahmegerät nicht erstellen. Dies kann auftreten, wenn das Audioendpunktgerät nicht angeschlossen wurde oder die Audiohardware oder die zugehörigen Hardwareressourcen neu konfiguriert, deaktiviert, entfernt oder anderweitig nicht mehr zur Verwendung verfügbar gemacht wurden.
AUDCLNT_E_INVALID_DEVICE_PERIOD	Hinweis Gilt für Windows 7 und höher. Gibt an, dass der von einem Client im exklusiven Modus angeforderte Gerätezeitraum größer als 5000 Millisekunden ist.
AUDCLNT_E_UNSUPPORTED_FORMAT	Die Audio-Engine (freigegebener Modus) oder das Audioendpunktgerät (exklusiver Modus) unterstützt das angegebene Format nicht.
AUDCLNT_E_EXCLUSIVE_MODE_NOT_ALLOWED	Der Aufrufer fordert die Verwendung des Endpunktgeräts im exklusiven Modus an, aber der Benutzer hat die Verwendung im exklusiven Modus des Geräts deaktiviert.
AUDCLNT_E_BUFDURATION_PERIOD_NOT_EQUAL	Das AUDCLNT_STREAMFLAGS_EVENTCALLBACK Flag ist festgelegt, aber die Parameter hnsBufferDuration und hnsPeriodicity sind nicht gleich.
AUDCLNT_E_SERVICE_NOT_RUNNING	Der Windows-Audiodienst wird nicht ausgeführt.
E_POINTER	Parameter pFormat ist NULL.
E_INVALIDARG	Parameter pFormat verweist auf eine ungültige Formatbeschreibung; oder das AUDCLNT_STREAMFLAGS_LOOPBACK-Flag ist festgelegt, aber ShareMode ist nicht gleich AUDCLNT_SHAREMODE_SHARED; oder das AUDCLNT_STREAMFLAGS_CROSSPROCESS flag ist festgelegt, aber ShareMode ist gleich AUDCLNT_SHAREMODE_EXCLUSIVE. Ein vorheriger Aufruf von SetClientProperties wurde mit einer ungültigen Kategorie für Audio-/Renderstreams durchgeführt.
E_OUTOFMEMORY	Nicht genügend Arbeitsspeicher.

Hinweise

Nach dem Aktivieren einer IAudioClient-Schnittstelle auf einem Audioendpunktgerät muss der Client Initialize einmal und nur einmal erfolgreich aufrufen, um den Audiodatenstrom zwischen dem Client und dem Gerät zu initialisieren. Der Client kann entweder direkt eine Verbindung mit der Audiohardware (exklusiver Modus) oder indirekt über die Audio-Engine (freigegebener Modus) herstellen. Im Initialize-Aufruf gibt der Client das Audiodatenformat, die Puffergröße und die Audiositzung für den Stream an.

Hinweis In Windows 8 sollte die erste Verwendung von IAudioClient für den Zugriff auf das Audiogerät im STA-Thread erfolgen. Aufrufe aus einem MTA-Thread können zu undefiniertem Verhalten führen.

Ein Versuch, einen Stream im freigegebenen Modus zu erstellen, kann nur erfolgreich sein, wenn das Audiogerät bereits im freigegebenen Modus ausgeführt wird oder das Gerät derzeit nicht verwendet wird. Ein Versuch, einen Stream im gemeinsamen Modus zu erstellen, schlägt fehl, wenn das Gerät bereits im exklusiven Modus ausgeführt wird.

Wenn ein Stream als ereignisgesteuert und im freigegebenen Modus initialisiert wird, wird ShareMode auf AUDCLNT_SHAREMODE_SHARED festgelegt, und eines der festgelegten Streamflags enthält AUDCLNT_STREAMFLAGS_EVENTCALLBACK. Für einen solchen Stream muss die zugeordnete Anwendung auch ein Handle abrufen, indem sie IAudioClient::SetEventHandle aufruft. Wenn es an der Zeit ist, den Stream außer Betrieb zu nehmen, kann die Audio-Engine dann das Handle verwenden, um die Streamobjekte freizugeben. Wenn IAudioClient::SetEventHandle vor dem Freigeben der Streamobjekte nicht aufgerufen wird, kann dies zu einer Verzögerung von mehreren Sekunden (einem Timeoutzeitraum) führen, während die Audio-Engine auf ein verfügbares Handle wartet. Nach Ablauf des Timeoutzeitraums gibt die Audio-Engine die Streamobjekte frei.

Ob ein Versuch, einen Datenstrom im exklusiven Modus zu erstellen, erfolgreich ist, hängt von mehreren Faktoren ab, einschließlich der Verfügbarkeit des Geräts und den vom Benutzer gesteuerten Einstellungen, die den Exklusivmodus des Geräts steuern. Weitere Informationen finden Sie unter Datenströme im exklusiven Modus.

Ein IAudioClient-Objekt unterstützt genau eine Verbindung mit der Audio-Engine oder Audiohardware. Diese Verbindung dauert die Lebensdauer des IAudioClient-Objekts .

Der Client sollte die folgenden Methoden erst nach dem Aufruf vonInitialize aufrufen:

Die folgenden Methoden erfordern nicht, dass Initialize zuerst aufgerufen wird:

Diese Methoden können jederzeit nach dem Aktivieren der IAudioClient-Schnittstelle aufgerufen werden.

Vor dem Aufrufen von Initialize zum Einrichten einer Verbindung im gemeinsamen Modus oder exklusiven Modus kann der Client die IAudioClient::IsFormatSupported-Methode aufrufen, um zu ermitteln, ob die Audio-Engine oder das Audioendpunktgerät ein bestimmtes Format in diesem Modus unterstützt. Vor dem Öffnen einer Verbindung im gemeinsamen Modus kann der Client das Mixformat der Audio-Engine abrufen, indem er die IAudioClient::GetMixFormat-Methode aufruft .

Der Endpunktpuffer, der zwischen Client und Audio-Engine gemeinsam genutzt wird, muss groß genug sein, um Störungen im Audiodatenstrom zwischen verarbeitungsdurchgängen durch den Client und der Audio-Engine zu verhindern. Für einen Renderingendpunkt schreibt der Clientthread in regelmäßigen Abständen Daten in den Puffer, und der Audio-Engine-Thread liest regelmäßig Daten aus dem Puffer. Bei einem Erfassungsendpunkt schreibt der Engine-Thread in regelmäßigen Abständen in den Puffer, und der Clientthread liest regelmäßig aus dem Puffer. Wenn die Zeiträume des Clientthreads und des Enginethreads nicht gleich sind, muss der Puffer in beiden Fällen groß genug sein, um die längeren der beiden Zeiträume zu berücksichtigen, ohne dass Störungen auftreten.

Der Client gibt eine Puffergröße über den hnsBufferDuration-Parameter an . Der Client ist dafür verantwortlich, einen Puffer anzufordern, der groß genug ist, um sicherzustellen, dass zwischen den regelmäßigen Verarbeitungsdurchläufen, die er für den Puffer ausführt, keine Störungen auftreten können. Ebenso stellt die Initialize-Methode sicher, dass der Puffer niemals kleiner als die erforderliche Mindestpuffergröße ist, um sicherzustellen, dass zwischen den regelmäßigen Verarbeitungsdurchläufen, die der Enginethread für den Puffer ausführt, keine Störungen auftreten. Wenn der Client eine Puffergröße anfordert, die kleiner als die erforderliche Mindestpuffergröße der Audio-Engine ist, legt die Methode die Puffergröße auf diese Mindestpuffergröße und nicht auf die vom Client angeforderte Puffergröße fest.

Wenn der Client eine Puffergröße anfordert (über den hnsBufferDuration-Parameter ), die keine integrale Anzahl von Audioframes ist, rundet die Methode die angeforderte Puffergröße auf die nächste integrale Anzahl von Frames auf.

Nach dem Initialize-Aufruf sollte der Client die IAudioClient::GetBufferSize-Methode aufrufen, um die genaue Größe des Endpunktpuffers abzurufen. Während jedes Verarbeitungsdurchlaufs benötigt der Client die tatsächliche Puffergröße, um zu berechnen, wie viele Daten in den oder aus dem Puffer übertragen werden sollen. Der Client ruft die IAudioClient::GetCurrentPadding-Methode auf, um zu bestimmen, wie viele der Daten im Puffer derzeit für die Verarbeitung verfügbar sind.

Um die minimale Streamlatenz zwischen der Clientanwendung und dem Audioendpunktgerät zu erreichen, sollte der Clientthread im gleichen Zeitraum wie der Audio-Engine-Thread ausgeführt werden. Der Zeitraum des Enginethreads ist festgelegt und kann nicht vom Client gesteuert werden. Wenn der Zeitraum des Clients unnötig kleiner als der Zeitraum der Engine ist, erhöht sich die Auslastung des Clientthreads auf den Prozessor, ohne die Latenz zu verbessern oder die Puffergröße zu verringern. Um den Zeitraum des Enginethreads zu bestimmen, kann der Client die IAudioClient::GetDevicePeriod-Methode aufrufen. Um den Puffer auf die für den Engine-Thread erforderliche Mindestgröße festzulegen, sollte der Client Initialize aufrufen, wobei der hnsBufferDuration-Parameter auf 0 festgelegt ist. Nach dem Initialize-Aufruf kann der Client die Größe des resultierenden Puffers abrufen, indem er IAudioClient::GetBufferSize aufruft.

Ein Client hat die Möglichkeit, eine Puffergröße anzufordern, die größer als die unbedingt erforderliche ist, um Zeitstörungen selten oder nicht vorhanden zu machen. Das Erhöhen der Puffergröße erhöht nicht notwendigerweise die Streamlatenz. Bei einem Renderingdatenstrom wird die Latenz durch den Puffer ausschließlich durch die Trennung zwischen dem Schreibzeiger des Clients und dem Lesezeiger der Engine bestimmt. Bei einem Erfassungsdatenstrom wird die Latenz durch den Puffer ausschließlich durch die Trennung zwischen dem Schreibzeiger der Engine und dem Lesezeiger des Clients bestimmt.

Das Loopbackflag (AUDCLNT_STREAMFLAGS_LOOPBACK) ermöglicht das Audioschleifenback. Ein Client kann Audioschleifeback nur auf einem Renderingendpunkt mit einem Stream im freigegebenen Modus aktivieren. Audio-Loopback wird hauptsächlich zur Unterstützung der akustischen Echounterdrückung (Acoustic Echo Cancellation, AEC) bereitgestellt.

Ein AEC-Client erfordert sowohl einen Renderingendpunkt als auch die Möglichkeit, den Ausgabedatenstrom von der Audio-Engine zu erfassen. Der Ausgabestream der Engine ist die globale Mischung, die das Audiogerät über die Lautsprecher abgibt. Wenn audio loopback aktiviert ist, kann ein Client einen Erfassungspuffer für den globalen Audiomix öffnen, indem er die IAudioClient::GetService-Methode aufruft, um eine IAudioCaptureClient-Schnittstelle für das Renderingstreamobjekt abzurufen. Wenn das Audioschleifenback nicht aktiviert ist, schlägt der Versuch, einen Erfassungspuffer für einen Renderingdatenstrom zu öffnen, fehl. Die Loopbackdaten im Erfassungspuffer haben das Geräteformat, das der Client durch Abfragen der PKEY_AudioEngine_DeviceFormat-Eigenschaft des Geräts abrufen kann.

Unter Windows-Versionen vor Windows 10 empfängt ein Aufzeichnungsclient im Pullmodus keine Ereignisse, wenn ein Stream mit ereignisgesteuerter Pufferung (AUDCLNT_STREAMFLAGS_EVENTCALLBACK) initialisiert und loopbackfähig (AUDCLNT_STREAMFLAGS_LOOPBACK) ist. Wenn der Stream mit dieser Konfiguration geöffnet wird, ist der Initialize-Aufruf erfolgreich, aber es werden keine relevanten Ereignisse ausgelöst, um den Aufzeichnungsclient jedes Mal zu benachrichtigen, wenn ein Puffer für die Verarbeitung bereit ist. Um dies zu umgehen, initialisieren Sie einen Renderdatenstrom im ereignisgesteuerten Modus. Jedes Mal, wenn der Client ein Ereignis für den Renderdatenstrom empfängt, muss er dem Aufzeichnungsclient signalisieren, dass er den Erfassungsthread ausführt, der den nächsten Satz von Beispielen aus dem Erfassungsendpunktpuffer liest. Ab Windows 10 die relevanten Ereignishandles jetzt für aktive Streams mit Aktiviertem Loopback festgelegt.

Beachten Sie, dass alle Streams im Freigabemodus geöffnet werden müssen, da Datenströme im exklusiven Modus nicht im Loopbackmodus ausgeführt werden können. Weitere Informationen zum Audio-Loopback finden Sie unter Loopbackaufzeichnung.

Das flag AUDCLNT_STREAMFLAGS_EVENTCALLBACK gibt an, dass die Verarbeitung des Audiopuffers durch den Client ereignisgesteuert erfolgt. WASAPI unterstützt ereignisgesteuerte Pufferung, um die Verarbeitung von Datenströmen im freigegebenen Modus und im exklusiven Modus mit geringer Latenz zu ermöglichen.

Die erste Version von Windows Vista unterstützt ereignisgesteuerte Pufferung (d. h. die Verwendung des AUDCLNT_STREAMFLAGS_EVENTCALLBACK Flags) nur für Renderingdatenströme.

In der ersten Version von Windows Vista wird für Aufzeichnungsstreams das Flag AUDCLNT_STREAMFLAGS_EVENTCALLBACK nur im freigegebenen Modus unterstützt. Das Festlegen dieses Flags hat keine Auswirkungen auf Aufzeichnungsdatenströme im exklusiven Modus. Das heißt, obwohl die Anwendung dieses Flag im exklusiven Modus über den Initialize-Aufruf angibt, empfängt die Anwendung keine Ereignisse, die normalerweise zum Erfassen des Audiodatenstroms erforderlich sind. Im Windows Vista Service Pack 1-Release ist dieses Flag im gemeinsam genutzten Modus und im exklusiven Modus funktionsfähig. Eine Anwendung kann dieses Flag festlegen, um die Ereignispufferung für Erfassungsstreams zu aktivieren. Weitere Informationen zum Erfassen eines Audiodatenstroms finden Sie unter Erfassen eines Datenstroms.

Um die ereignisgesteuerte Pufferung zu aktivieren, muss der Client dem System ein Ereignishandle bereitstellen. Nach dem Initialize-Aufruf und vor dem Aufrufen der IAudioClient::Start-Methode zum Starten des Datenstroms muss der Client die IAudioClient::SetEventHandle-Methode aufrufen, um das Ereignishandle festzulegen. Während der Datenstrom ausgeführt wird, signalisiert das System in regelmäßigen Abständen das Ereignis, um dem Client mitzuteilen, dass Audiodaten für die Verarbeitung verfügbar sind. Zwischen verarbeitungsdurchläufen wartet der Clientthread auf das Ereignishandle, indem er eine Synchronisierungsfunktion wie WaitForSingleObject aufruft. Weitere Informationen zu Synchronisierungsfunktionen finden Sie in der Windows SDK-Dokumentation.

Für einen Stream im freigegebenen Modus, der ereignisgesteuerte Pufferung verwendet, muss der Aufrufer sowohl hnsPeriodicity als auch hnsBufferDuration auf 0 festlegen. Die Initialize-Methode bestimmt, wie groß ein Puffer zugeordnet werden soll, basierend auf dem Planungszeitraum der Audio-Engine. Obwohl der Pufferverarbeitungsthread des Clients ereignisgesteuert ist, bleibt der grundlegende Pufferverwaltungsprozess, wie zuvor beschrieben, unverändert. Jedes Mal, wenn der Thread erwacht, sollte er IAudioClient::GetCurrentPadding aufrufen, um zu bestimmen, wie viele Daten in einen Renderingpuffer geschrieben oder aus einem Erfassungspuffer gelesen werden sollen. Im Gegensatz zu den beiden Puffern, die die Initialize-Methode einem Datenstrom im exklusiven Modus zuordnet, der ereignisgesteuerte Pufferung verwendet, erfordert ein Stream im freigegebenen Modus einen einzelnen Puffer.

Für einen Datenstrom im exklusiven Modus, der ereignisgesteuerte Pufferung verwendet, muss der Aufrufer Werte ungleich null für hnsPeriodicity und hnsBufferDuration angeben, und die Werte dieser beiden Parameter müssen gleich sein. Die Initialize-Methode weist zwei Puffer für den Stream zu. Jeder Puffer ist in der Dauer gleich dem Wert des hnsBufferDuration-Parameters . Nach dem Initialize-Aufruf für einen Renderingstream sollte der Aufrufer den ersten der beiden Puffer füllen, bevor er den Datenstrom startet. Bei einem Erfassungsdatenstrom sind die Puffer anfänglich leer, und der Aufrufer sollte davon ausgehen, dass jeder Puffer leer bleibt, bis das Ereignis für diesen Puffer signalisiert wird. Während der Datenstrom ausgeführt wird, sendet das System abwechselnd einen oder einen anderen Puffer an den Client. Diese Form der doppelten Pufferung wird als "Ping-Ponging" bezeichnet. Jedes Mal, wenn der Client einen Puffer vom System empfängt (den das System durch Signalisierung des Ereignisses angibt), muss der Client den gesamten Puffer verarbeiten. Wenn der Client beispielsweise eine Paketgröße von der IAudioRenderClient::GetBuffer-Methode anfordert, die nicht mit der Puffergröße übereinstimmt, schlägt die Methode fehl. Aufrufe der IAudioClient::GetCurrentPadding-Methode sind nicht erforderlich, da die Paketgröße immer der Puffergröße entsprechen muss. Im Gegensatz zu den zuvor beschriebenen Puffermodi hängt die Latenz für einen ereignisgesteuerten Datenstrom im exklusiven Modus direkt von der Puffergröße ab.

Wie in Audiositzungen erläutert, besteht das Standardverhalten für eine Sitzung, die Renderingdatenströme enthält, darin, dass die Einstellungen für Volume und Stummschaltung über Anwendungsneustarts hinweg beibehalten werden. Das AUDCLNT_STREAMFLAGS_NOPERSIST-Flag überschreibt das Standardverhalten und macht die Einstellungen nicht permanent. Dieses Flag hat keine Auswirkungen auf Sitzungen, die Aufzeichnungsstreams enthalten. Die Einstellungen für diese Sitzungen sind nie persistent. Darüber hinaus sind die Einstellungen für eine Sitzung, die einen Loopbackdatenstrom enthält (ein Stream, der mit dem flag AUDCLNT_STREAMFLAGS_LOOPBACK initialisiert wird) nicht persistent.

Nur eine Sitzung, die eine Verbindung mit einem Renderingendpunktgerät herstellt, kann persistente Volume- und Stummschaltungseinstellungen aufweisen. Der erste Stream, der der Sitzung hinzugefügt wird, bestimmt, ob die Einstellungen der Sitzung persistent sind. Wenn also das AUDCLNT_STREAMFLAGS_NOPERSIST- oder AUDCLNT_STREAMFLAGS_LOOPBACK-Flag während der Initialisierung des ersten Datenstroms festgelegt wird, sind die Einstellungen der Sitzung nicht persistent. Andernfalls sind sie persistent. Ihre Persistenz ist von zusätzlichen Datenströmen nicht betroffen, die später während der Lebensdauer des Sitzungsobjekts hinzugefügt oder entfernt werden können.

Nachdem ein Aufruf von Initialize erfolgreich eine IAudioClient-Schnittstelle instance initialisiert hat, schlägt ein nachfolgender Initialize-Aufruf zum Initialisieren derselben Schnittstelle instance fehl und gibt den Fehlercode E_ALREADY_INITIALIZED zurück.

Wenn der anfängliche Aufruf von Initialize fehlschlägt, können nachfolgende Initialize-Aufrufe fehlschlagen und fehlercode E_ALREADY_INITIALIZED zurückgeben, auch wenn die Schnittstelle nicht initialisiert wurde. Geben Sie in diesem Fall die IAudioClient-Schnittstelle frei, und rufen Sie eine neue IAudioClient-Schnittstelle von der MMDevice-API ab, bevor Sie Initialize erneut aufrufen.

Codebeispiele, die die Initialize-Methode aufrufen, finden Sie in den folgenden Themen:

Ab Windows 7 kann Initialize AUDCLNT_E_BUFFER_SIZE_NOT_ALIGNED für ein Render- oder Aufnahmegerät zurückgeben. Dies gibt an, dass die Puffergröße, die vom Aufrufer im hnsBufferDuration-Parameter angegeben wird, nicht ausgerichtet ist. Dieser Fehlercode wird nur zurückgegeben, wenn der Aufrufer einen Datenstrom im exklusiven Modus (AUDCLNT_SHAREMODE_EXCLUSIVE) und ereignisgesteuerte Pufferung (AUDCLNT_STREAMFLAGS_EVENTCALLBACK) angefordert hat.

Wenn Initialize AUDCLNT_E_BUFFER_SIZE_NOT_ALIGNED zurückgibt, muss der Aufrufer Initialize erneut aufrufen und die ausgerichtete Puffergröße angeben. Führen Sie die folgenden Schritte durch:

Rufen Sie IAudioClient::GetBufferSize auf, und erhalten Sie die nächsthöher ausgerichtete Puffergröße (in Frames).
Rufen Sie IAudioClient::Release auf, um den Audioclient freizugeben, der im vorherigen Aufruf verwendet wurde, der AUDCLNT_E_BUFFER_SIZE_NOT_ALIGNED zurückgegeben hat.
Berechnen Sie die ausgerichtete Puffergröße in 100 Nanosekundeneinheiten (hns). Die Puffergröße ist (REFERENCE_TIME)((10000.0 * 1000 / WAVEFORMATEX.nSamplesPerSecond * nFrames) + 0.5). In dieser Formel nFrames ist die von GetBufferSize abgerufene Puffergröße.
Rufen Sie die IMMDevice::Activate-Methode mit parameter iid auf REFIID IID_IAudioClient auf, um einen neuen Audioclient zu erstellen.
Rufen Sie Initialize auf dem erstellten Audioclient erneut auf, und geben Sie die neue Puffergröße und Periodizität an.

Ab Windows 10 müssen hardwareoffene Audiodatenströme ereignisgesteuert sein. Wenn Sie also IAudioClient2::SetClientProperties aufrufen und den bIsOffload-Parameter der AudioClientProperties auf TRUE festlegen, müssen Sie das flag AUDCLNT_STREAMFLAGS_EVENTCALLBACK im StreamFlags-Parameter auf IAudioClient::Initialize angeben.

Beispiele

Der folgende Beispielcode zeigt, wie auf den AUDCLNT_E_BUFFER_SIZE_NOT_ALIGNED Rückgabecode reagiert wird.

#define REFTIMES_PER_SEC  10000000

HRESULT CreateAudioClient(IMMDevice* pDevice, IAudioClient** ppAudioClient)
{
    if (!pDevice)
    {
        return E_INVALIDARG;
    }

    if (!ppAudioClient)
    {
        return E_POINTER;
    }

    HRESULT hr = S_OK;
    
    WAVEFORMATEX *pwfx = NULL;

    REFERENCE_TIME hnsRequestedDuration = REFTIMES_PER_SEC;

    UINT32 nFrames = 0;

    IAudioClient *pAudioClient = NULL;

    // Get the audio client.
    CHECK_HR( hr = pDevice->Activate(
        __uuidof(IAudioClient), 
        CLSCTX_ALL,
        NULL, 
        (void**)&pAudioClient));

    // Get the device format.
    CHECK_HR( hr = pAudioClient->GetMixFormat(&pwfx));

    // Open the stream and associate it with an audio session.
    hr = pAudioClient->Initialize( 
        AUDCLNT_SHAREMODE_EXCLUSIVE,
        AUDCLNT_STREAMFLAGS_EVENTCALLBACK, 
        hnsRequestedDuration, 
        hnsRequestedDuration, 
        pwfx, 
        NULL);

    // If the requested buffer size is not aligned...
    if (hr == AUDCLNT_E_BUFFER_SIZE_NOT_ALIGNED)
    {	
        // Get the next aligned frame.
        CHECK_HR( hr = pAudioClient->GetBufferSize(&nFrames));
        
        hnsRequestedDuration = (REFERENCE_TIME)
        ((10000.0 * 1000 / pwfx->nSamplesPerSec * nFrames) + 0.5);

        // Release the previous allocations.
        SAFE_RELEASE(pAudioClient);
        CoTaskMemFree(pwfx);
        
        // Create a new audio client.
        CHECK_HR( hr = pDevice->Activate(
            __uuidof(IAudioClient), 
            CLSCTX_ALL,
            NULL, 
            (void**)&pAudioClient));
    
        // Get the device format.
        CHECK_HR( hr = pAudioClient->GetMixFormat(&pwfx));
        
        // Open the stream and associate it with an audio session.
        CHECK_HR( hr = pAudioClient->Initialize( 
            AUDCLNT_SHAREMODE_EXCLUSIVE,
            AUDCLNT_STREAMFLAGS_EVENTCALLBACK, 
            hnsRequestedDuration, 
            hnsRequestedDuration, 
            pwfx, 
            NULL));
    }
    else
    {
        CHECK_HR (hr);
    }
    
    // Return to the caller.
    *(ppAudioClient) = pAudioClient;
    (*ppAudioClient)->AddRef();

done:

    // Clean up.
    CoTaskMemFree(pwfx);
    SAFE_RELEASE(pAudioClient);
    return hr;
}