(audioclient.h) IAudioRenderClient：：GetBuffer 方法

發行項
02/23/2024

擷取轉譯端點緩衝區中下一個可用空間的指標，讓呼叫端可以寫入數據封包。

語法

HRESULT GetBuffer(
  [in]  UINT32 NumFramesRequested,
  [out] BYTE   **ppData
);

參數

[in] NumFramesRequested

呼叫端計劃寫入緩衝區中要求空間的數據封包中的音訊畫面數。如果呼叫成功， *ppData 指向的緩衝區區域大小會符合 NumFramesRequested 中指定的大小。

[out] ppData

指標變數的指標，方法會將呼叫者寫入數據封包的緩衝區區域起始位址。

傳回值

如果方法成功，它會傳回 S_OK。如果失敗，可能的傳回碼包括但不限於下表所示的值。

傳回碼	Description
AUDCLNT_E_BUFFER_ERROR	GetBuffer 無法擷取數據緩衝區，而 *ppData 指向 NULL。如需詳細資訊，請參閱＜備註＞。
AUDCLNT_E_BUFFER_TOO_LARGE	NumFramesRequested 值超過可用緩衝區空間， (緩衝區大小減去填補大小) 。
AUDCLNT_E_BUFFER_SIZE_ERROR	數據流是獨佔模式，並使用事件驅動緩衝，但客戶端嘗試取得不是緩衝區大小的封包。
AUDCLNT_E_OUT_OF_ORDER	先前的 IAudioRenderClient：：GetBuffer 呼叫仍然有效。
AUDCLNT_E_DEVICE_INVALIDATED	音訊端點裝置已解除叢集，或音訊硬體或相關聯的硬體資源已重新設定、停用、移除或無法使用。
AUDCLNT_E_BUFFER_OPERATION_PENDING	無法存取緩衝區，因為數據流重設正在進行中。
AUDCLNT_E_SERVICE_NOT_RUNNING	Windows 音訊服務未執行。
E_POINTER	參數 ppData 為 NULL。

備註

呼叫端可以要求小於或等於緩衝區中可用空間量的封包大小 (，但使用事件驅動緩衝的獨佔模式數據流除外;如需詳細資訊，請參閱 IAudioClient：：Initialize) 。可用空間只是緩衝區大小減去緩衝區中已排入佇列以播放的數據量。如果呼叫端指定超過緩衝區可用空間的 NumFramesRequested 值，則呼叫會失敗並傳回錯誤碼AUDCLNT_E_BUFFER_TOO_LARGE。

用戶端負責將足夠的數據寫入緩衝區，以防止音訊數據流發生問題。如需緩衝需求的詳細資訊，請參閱 IAudioClient：：Initialize。

藉由呼叫 GetBuffer 取得數據封包之後，用戶端會將轉譯數據填入封包，並藉由呼叫 IAudioRenderClient：：ReleaseBuffer 方法向音訊引擎發出封包。

客戶端必須在 GetBuffer 呼叫之後呼叫 ReleaseBuffer，才能成功取得任何大小為 0 的封包。用戶端可以選擇呼叫或未呼叫 ReleaseBuffer 來釋放大小為 0 的封包。

針對非零封包大小，客戶端必須替代 對 GetBuffer 和 ReleaseBuffer 的呼叫。每個 GetBuffer 呼叫後面都必須接著對應的 ReleaseBuffer 呼叫。在用戶端呼叫 GetBuffer 以取得數據封包之後，除非用戶端呼叫 ReleaseBuffer 來釋放先前的封包，否則客戶端無法取得下一個數據封包。不允許對 GetBuffer 或 ReleaseBuffer 進行兩個以上的連續呼叫，而且會失敗並出現錯誤碼AUDCLNT_E_OUT_OF_ORDER。

若要確保呼叫的排序正確， GetBuffer 呼叫及其對應的 ReleaseBuffer 呼叫必須在相同的線程中發生。

音訊框架的大小是由客戶端藉由呼叫 IAudioClient：：GetMixFormat 方法取得的顯示方式，由其所取得的顯示方式為其NBlockAlign 成員所指定。

如果呼叫端設定 NumFramesRequested = 0，此方法會傳回狀態代碼S_OK，但不會寫入 ppData 參數所指向的變數。

客戶端應該避免 GetBuffer 呼叫之間取得緩衝區和釋放緩衝區的 ReleaseBuffer 呼叫之間的過度延遲。音訊引擎的實作假設 GetBuffer 呼叫和對應的 ReleaseBuffer 呼叫發生在相同的緩衝區處理期間內。延遲釋放緩衝區超過一段時間的用戶端，可能會遺失範例數據。

在 Windows 7 中， GetBuffer 可以針對在獨佔模式中使用端點緩衝區的音訊用戶端傳回 AUDCLNT_E_BUFFER_ERROR 錯誤碼。此錯誤表示數據緩衝區未擷取，因為數據封包無法使用， (*ppData 收到 NULL) 。

如果 GetBuffer 傳回 AUDCLNT_E_BUFFER_ERROR，取用音訊樣本的線程必須等候下一個處理階段。用戶端可能會受益於保留失敗 GetBuffer 呼叫的計數。如果 GetBuffer 重複傳回此錯誤，用戶端可以在關閉目前客戶端之後啟動新的處理迴圈，方法是呼叫 IAudioClient：：Stop、IAudioClient：：Reset，以及釋放音訊用戶端。

範例

如需呼叫 GetBuffer 方法的程式代碼範例，請參閱下列主題：

規格需求

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