IAudioClient：：IsFormatSupported 方法 (audioclient.h)

  • 發行項

IsFormatSupported 方法會指出音訊端點裝置是否支援特定的數據流格式。

語法

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

參數

[in] ShareMode

數據流格式的共用模式。 透過此參數，用戶端會指出它想要以獨佔模式或共用模式使用指定的格式。 客戶端應該將此參數設定為下列其中一個 AUDCLNT_SHAREMODE 列舉值：

AUDCLNT_SHAREMODE_EXCLUSIVE

AUDCLNT_SHAREMODE_SHARED

[in] pFormat

指定數據流格式的指標。 這個參數會指向 類型為 WAVEFORMATEX 或WAVEFORMATEXTENSIBLE 的呼叫端配置格式描述元。 用戶端會在呼叫此方法之前，先將格式描述寫入這個結構。 如需有關其與其產生方式的資訊，請參閱 Windows DDK 檔。

[out] ppClosestMatch

指標變數的指標，方法會將 其位址寫入到其中，而其為一個其其為一個其一或 二十二進位的 位址 。 這個結構會指定最接近透過 pFormat 參數指定之用戶端所指定格式的支援格式。 針對共用模式 (，也就是說，如果 ShareMode 參數AUDCLNT_SHAREMODE_SHARED) ，請將 ppClosestMatch 設定為指向有效的非 NULL 指標變數。 針對獨佔模式，請將 ppClosestMatch 設定為 NULL。 方法會配置 結構的記憶體。 呼叫端會藉由呼叫 CoTaskMemFree 函式，負責釋出不再需要的記憶體。 如果 IsFormatSupported 呼叫失敗，且 ppClosestMatch 為非 NULL，此方法會將 *ppClosestMatch 設定為 NULL。 如需 CoTaskMemFree 的相關信息，請參閱 Windows SDK 檔。

傳回值

傳回碼 描述
S_OK
 成功且音訊端點裝置支援指定的數據流格式。
S_FALSE
 成功與指定格式最接近的相符專案。
AUDCLNT_E_UNSUPPORTED_FORMAT
 成功，但獨佔模式不支援指定的格式。
 

如果作業失敗，可能的傳回碼包括但不限於下表所示的值。

傳回碼 Description
E_POINTER
 參數 pFormat 為 NULL，或 ppClosestMatch 為 NULL ，且 ShareMode 為AUDCLNT_SHAREMODE_SHARED。
E_INVALIDARG
 Parameter ShareMode 是AUDCLNT_SHAREMODE_SHARED或AUDCLNT_SHAREMODE_EXCLUSIVE以外的值。
AUDCLNT_E_DEVICE_INVALIDATED
 音訊端點裝置已解除叢集，或音訊硬體或相關聯的硬體資源已重新設定、停用、移除，否則無法使用。
AUDCLNT_E_SERVICE_NOT_RUNNING
 Windows 音訊服務未執行。

備註

這個方法提供一種方式，讓用戶端在呼叫 IAudioClient：：Initialize 之前，音訊引擎是否支援特定的數據流格式。

針對獨佔模式， IsFormatSupported 如果音訊端點裝置支援呼叫端指定的格式，則會傳回S_OK;如果裝置不支援格式，則會傳回AUDCLNT_E_UNSUPPORTED_FORMAT。 ppClosestMatch 參數可以是 NULL。 如果不是 NULL，此方法會將 NULL 寫入 *ppClosestMatch。

針對共用模式，如果音訊引擎支援呼叫端指定的格式， IsFormatSupported 會將 *ppClosestMatch 設定為 NULL ，並傳回S_OK。 如果音訊引擎不支援呼叫端指定的格式，但支援類似的格式，此方法會透過 ppClosestMatch 參數擷取類似的格式，並傳回S_FALSE。 如果音訊引擎不支援呼叫端指定的格式或任何類似的格式，此方法會將 *ppClosestMatch 設定為 NULL ，並傳回AUDCLNT_E_UNSUPPORTED_FORMAT。

在共用模式中，音訊引擎一律支援混合格式，用戶端可以藉由呼叫 IAudioClient：：GetMixFormat 方法來取得。 此外，音訊引擎可能支援與混合格式相同的取樣速率和通道數目的類似格式，但在音訊樣本值的表示方式上不同。 音訊引擎會在內部以浮點數表示樣本值，但如果呼叫端指定的格式以整數表示樣本值，音訊引擎通常可以在整數樣本值與其內部浮點表示之間轉換。

如果音訊裝置的安裝套件包含本機效果 (LFX) 音訊處理物件， (APO) 可以處理格式轉換，音訊引擎可能會支援更廣泛的共用模式格式。 LFX APO 是軟體模組，可執行音訊數據流的裝置特定處理。 Windows 音訊服務中的音訊圖形產生器會將 LFX APO 插入每個用戶端與音訊引擎之間的數據流。 當用戶端呼叫 IsFormatSupported 方法，而方法會判斷已安裝 LFX APO 以搭配裝置使用時，此方法會將查詢導向至 LFX APO，指出它是否支援呼叫端指定的格式。

例如，特定 LFX APO 可能會接受來自用戶端的 6 通道環繞音效串流，並將串流轉換成可透過耳機播放的立體格式。 一般而言，LFX APO 僅支援符合混合格式取樣率的樣本速率的用戶端格式。

如需 API 的詳細資訊，請參閱 Windows 音訊處理物件。 如需 IsFormatSupported 方法的詳細資訊，請參閱 裝置格式。

規格需求

需求 值
最低支援的用戶端 Windows Vista [傳統型應用程式 |UWP 應用程式]
最低支援的伺服器 Windows Server 2008 [傳統型應用程式 |UWP 應用程式]
目標平台 Windows
標頭 audioclient.h

另請參閱

IAudioClient 介面

IAudioClient：：GetMixFormat

IAudioClient：：Initialize