IAudioClient::IsFormatSupported-Methode (audioclient.h)

  • Artikel

Die IsFormatSupported-Methode gibt an, ob das Audioendpunktgerät ein bestimmtes Streamformat unterstützt.

Syntax

HRESULT IsFormatSupported(
  [in]  AUDCLNT_SHAREMODE  ShareMode,
  [in]  const WAVEFORMATEX *pFormat,
  [out] WAVEFORMATEX       **ppClosestMatch
);

Parameter

[in] ShareMode

Der Freigabemodus für das Streamformat. Mit diesem Parameter gibt der Client an, ob er das angegebene Format im exklusiven Modus oder im freigegebenen Modus verwenden möchte. Der Client sollte diesen Parameter auf einen der folgenden AUDCLNT_SHAREMODE Enumerationswerte festlegen:

AUDCLNT_SHAREMODE_EXCLUSIVE

AUDCLNT_SHAREMODE_SHARED

[in] pFormat

Zeiger auf das angegebene Streamformat. Dieser Parameter verweist auf einen vom Aufrufer zugewiesenen Formatdeskriptor vom Typ WAVEFORMATEX oder WAVEFORMATEXTENSIBLE. Der Client schreibt eine Formatbeschreibung in diese Struktur, bevor er diese Methode aufruft. Informationen zu WAVEFORMATEX und WAVEFORMATEXTENSIBLE finden Sie in der Dokumentation zu Windows DDK.

[out] ppClosestMatch

Zeiger auf eine Zeigervariable, in die die -Methode die Adresse einer WAVEFORMATEX - oder WAVEFORMATEXTENSIBLE-Struktur schreibt. Diese Struktur gibt das unterstützte Format an, das dem Format am nächsten kommt, das der Client über den pFormat-Parameter angegeben hat. Legen Sie für den freigegebenen Modus (d. h. wenn der ShareMode-Parameter AUDCLNT_SHAREMODE_SHARED ist) ppClosestMatch so fest, dass er auf eine gültige Zeigervariable ohne NULL verweist. Legen Sie für den exklusiven Modus ppClosestMatch auf NULL fest. Die -Methode weist den Speicher für die Struktur zu. Der Aufrufer ist für das Freigeben des Speichers verantwortlich, wenn er nicht mehr benötigt wird, indem er die CoTaskMemFree-Funktion aufruft . Wenn der IsFormatSupported-Aufruf fehlschlägt und ppClosestMatch nicht NULL ist, legt die Methode *ppClosestMatch auf NULL fest. Informationen zu CoTaskMemFree finden Sie in der Dokumentation zum Windows SDK.

Rückgabewert

Rückgabecode BESCHREIBUNG
S_OK
 Erfolgreich, und das Audioendpunktgerät unterstützt das angegebene Streamformat.
S_FALSE
 Erfolgreich, wenn eine übereinstimmung mit dem angegebenen Format am nächsten ist.
AUDCLNT_E_UNSUPPORTED_FORMAT
 Erfolgreich, aber das angegebene Format wird im exklusiven Modus nicht unterstützt.
 

Wenn der Vorgang fehlschlägt, umfassen mögliche Rückgabecodes die Werte in der folgenden Tabelle, sind jedoch nicht darauf beschränkt.

Rückgabecode Beschreibung
E_POINTER
 Parameter pFormat ist NULL, oder ppClosestMatch ist NULL und ShareMode ist AUDCLNT_SHAREMODE_SHARED.
E_INVALIDARG
 Parameter ShareMode ist ein anderer Wert als AUDCLNT_SHAREMODE_SHARED oder AUDCLNT_SHAREMODE_EXCLUSIVE.
AUDCLNT_E_DEVICE_INVALIDATED
 Das Audioendpunktgerät wurde getrennt, oder die Audiohardware oder die zugehörigen Hardwareressourcen wurden neu konfiguriert, deaktiviert, entfernt oder anderweitig für die Verwendung nicht verfügbar gemacht.
AUDCLNT_E_SERVICE_NOT_RUNNING
 Der Windows-Audiodienst wird nicht ausgeführt.

Hinweise

Diese Methode bietet eine Möglichkeit für einen Client, vor dem Aufrufen von IAudioClient::Initialize zu bestimmen, ob die Audio-Engine ein bestimmtes Streamformat unterstützt.

Für den exklusiven Modus gibt IsFormatSupported S_OK zurück, wenn das Audioendpunktgerät das vom Aufrufer angegebene Format unterstützt, oder es gibt AUDCLNT_E_UNSUPPORTED_FORMAT zurück, wenn das Gerät das Format nicht unterstützt. Der ppClosestMatch-Parameter kann NULL sein. Wenn sie nicht NULL ist, schreibt die Methode NULL in *ppClosestMatch.

Wenn die Audio-Engine für den freigegebenen Modus das vom Aufrufer angegebene Format unterstützt, legt IsFormatSupported*ppClosestMatch auf NULL fest und gibt S_OK zurück. Wenn die Audio-Engine das vom Aufrufer angegebene Format nicht unterstützt, aber ein ähnliches Format unterstützt, ruft die -Methode das ähnliche Format über den ppClosestMatch-Parameter ab und gibt S_FALSE zurück. Wenn die Audio-Engine das vom Aufrufer angegebene Format oder ein ähnliches Format nicht unterstützt, legt die Methode *ppClosestMatch auf NULL fest und gibt AUDCLNT_E_UNSUPPORTED_FORMAT zurück.

Im freigegebenen Modus unterstützt die Audio-Engine immer das Mixformat, das der Client durch Aufrufen der IAudioClient::GetMixFormat-Methode abrufen kann. Darüber hinaus unterstützt die Audio-Engine möglicherweise ähnliche Formate, die die gleiche Abtastrate und Die gleiche Anzahl von Kanälen wie das Mixformat aufweisen, sich aber in der Darstellung der Audiobeispielwerte unterscheiden. Die Audio-Engine stellt Beispielwerte intern als Gleitkommazahlen dar, aber wenn das vom Aufrufer angegebene Format Beispielwerte als ganze Zahlen darstellt, kann die Audio-Engine in der Regel zwischen den ganzzahligen Beispielwerten und ihrer internen Gleitkommadarstellung konvertieren.

Die Audio-Engine kann möglicherweise eine noch größere Palette von Formaten im freigegebenen Modus unterstützen, wenn das Installationspaket für das Audiogerät ein LFX-Audioverarbeitungsobjekt (Local Effects) enthält, das Formatkonvertierungen verarbeiten kann. Ein LFX APO ist ein Softwaremodul, das gerätespezifische Verarbeitung eines Audiostreams durchführt. Der Audiograph-Generator im Windows-Audiodienst fügt den LFX APO zwischen jedem Client und der Audio-Engine in den Stream ein. Wenn ein Client die IsFormatSupported-Methode aufruft und die -Methode bestimmt, dass ein LFX APO zur Verwendung mit dem Gerät installiert ist, leitet die -Methode die Abfrage an den LFX-APO weiter, was angibt, ob sie das vom Aufrufer angegebene Format unterstützt.

Beispielsweise kann ein bestimmter LFX APO einen 6-Kanal-Surround-Soundstream von einem Client akzeptieren und den Stream in ein Stereoformat konvertieren, das über Kopfhörer wiedergegeben werden kann. In der Regel unterstützt ein LFX APO nur Clientformate mit Sampleraten, die der Abtastrate des Mixformats entsprechen.

Weitere Informationen zu APOs finden Sie unter Windows-Audioverarbeitungsobjekte. Weitere Informationen zur IsFormatSupported-Methode finden Sie unter Geräteformate.

Anforderungen

Anforderung Wert
Unterstützte Mindestversion (Client) Windows Vista [Desktop-Apps | UWP-Apps]
Unterstützte Mindestversion (Server) Windows Server 2008 [Desktop-Apps | UWP-Apps]
Zielplattform Windows
Kopfzeile audioclient.h

Weitere Informationen

IAudioClient-Schnittstelle

IAudioClient::GetMixFormat

IAudioClient::Initialize