IAudioCaptureClient：：GetBuffer 方法 (audioclient.h)
擷取端點緩衝區中下一個可用數據封包的指標。
語法
HRESULT GetBuffer(
[out] BYTE **ppData,
[out] UINT32 *pNumFramesToRead,
[out] DWORD *pdwFlags,
[out] UINT64 *pu64DevicePosition,
[out] UINT64 *pu64QPCPosition
);
參數
[out] ppData
指標變數的指標，此方法會寫入可供用戶端讀取之下一個數據封包的起始位址。
[out] pNumFramesToRead
UINT32 變數的指標，此方法會將畫面計數寫入其中 (數據封包中可用的音訊畫面數) 。 客戶端應該讀取整個數據封包，或完全不讀取。
[out] pdwFlags
方法將緩衝區狀態旗標寫入其中的 DWORD 變數指標。 方法會寫入下列一或多個 _AUDCLNT_BUFFERFLAGS 列舉值的 0 或位 OR 組合：
AUDCLNT_BUFFERFLAGS_SILENT
AUDCLNT_BUFFERFLAGS_DATA_DISCONTINUITY
AUDCLNT_BUFFERFLAGS_TIMESTAMP_ERROR
在 Windows 7 和更新版本的作業系統版本中，此旗標可用於問題偵測。 若要啟動擷取數據流，用戶端應用程式必須呼叫 IAudioClient：：Start ，然後呼叫迴圈中的 GetBuffer 來讀取數據封包，直到已讀取端點緩衝區中的所有可用封包為止。 GetBuffer 會設定 AUDCLNT_BUFFERFLAGS_DATA_DISCONTINUITY 旗標，以指出 ppData所指向緩衝區中的問題。
[out] pu64DevicePosition
UINT64 變數的指標，此方法會將第一個音訊框架的裝置位置寫入數據封包中。 裝置位置會以數據流開頭的音訊畫面數表示。 如果用戶端不需要裝置位置，這個參數可以是 NULL 。 如需詳細資訊，請參閱＜備註＞。
[out] pu64QPCPosition
UINT64 變數的指標，此方法會在音訊端點裝置記錄數據封包中第一個音訊畫面的裝置位置時寫入性能計數器的值。 方法會將計數器值轉換成 100 奈秒單位，再將其寫入 *pu64QPCPosition。 如果用戶端不需要性能計數器值，這個參數可以是 NULL 。 如需詳細資訊，請參閱＜備註＞。
傳回值
可能的傳回碼包括但不限於下表所示的值。
| 傳回碼 | 描述 |
|---|---|
|
呼叫成功且 *pNumFramesToRead 為非零值，表示封包已準備好讀取。 |
|
呼叫成功且 *pNumFramesToRead 為 0，表示無法讀取任何擷取數據。 |
|
Windows 7 和更新版本： GetBuffer 無法擷取數據緩衝區，而 *ppData 指向 NULL。 如需詳細資訊，請參閱＜備註＞。 |
|
先前的 IAudioCaptureClient：：GetBuffer 呼叫仍然有效。 |
|
音訊端點裝置已解除叢集，或音訊硬體或相關聯的硬體資源已重新設定、停用、移除或無法使用。 |
|
無法存取緩衝區，因為數據流重設正在進行中。 |
|
Windows 音訊服務未執行。 |
|
參數 ppData、pNumFramesToRead 或 pdwFlags 為 NULL。 |
備註
此方法會從擷取端點緩衝區擷取下一個數據封包。 在特定時間，緩衝區可能包含零、一或多個準備好讀取的封包。 一般而言，從擷取端點緩衝區讀取數據的緩衝區處理線程會在每次線程執行時讀取所有可用的封包。
在處理音訊擷取數據流期間，用戶端應用程式會替代呼叫 GetBuffer 和 IAudioCaptureClient：：ReleaseBuffer 方法。 客戶端無法讀取每個 GetBuffer 呼叫的單一數據封包。 在每個 GetBuffer 呼叫之後，客戶端必須呼叫 ReleaseBuffer 以釋放封包，用戶端才能再次呼叫 GetBuffer 以取得下一個封包。
不允許對 GetBuffer 或 ReleaseBuffer 進行兩個以上的連續呼叫，而且會失敗並出現錯誤碼AUDCLNT_E_OUT_OF_ORDER。 若要確保呼叫的排序正確， GetBuffer 呼叫及其對應的 ReleaseBuffer 呼叫必須在相同的線程中發生。
在每個 GetBuffer 呼叫期間，呼叫端必須取得整個封包，或沒有任何封包。 讀取封包之前，呼叫端可以透過 pNumFramesToRead 參數來檢查封包大小 (可用) ，以確保有足夠的空間可儲存整個封包。
在每個 ReleaseBuffer 呼叫期間，呼叫端會報告從緩衝區讀取的音訊畫面數。 此數字必須是 (非零) 封包大小或0。 如果號碼為 0，則下一個 GetBuffer 呼叫會呈現呼叫端與先前 GetBuffer 呼叫中相同的封包。
在每個 GetBuffer 呼叫之後，封包中的數據會維持有效狀態，直到下一個 ReleaseBuffer 呼叫釋放緩衝區為止。
客戶端必須在 GetBuffer 呼叫之後呼叫 ReleaseBuffer，才能成功取得任何大小為 0 的封包。 用戶端可以選擇呼叫或未呼叫 ReleaseBuffer 來釋放大小為 0 的封包。
方法會透過 pu64DevicePosition 和 pu64QPCPosition 輸出參數來輸出裝置位置和性能計數器。 這些值會提供數據封包中第一個音訊畫面的時間戳。 透過 pdwFlags 輸出參數，方法會指出回報的裝置位置是否有效。
方法寫入 *pu64DevicePosition 的裝置位置是目前透過喇叭播放的音訊畫面串流相對位置， (轉譯數據流) 或透過麥克風 (錄製擷取數據流) 。 位置會以數據流開頭的畫面數表示。 音訊數據流中的畫面格大小是由指定數據流格式的 ( 或 ) STRUCTUREATEXTENSIBLE 結構的 nBlockAlign 成員所指定。 音訊畫面的大小，以位元組為單位，等於數據流中的通道數目乘以每個通道的樣本大小。 例如，對於具有16位樣本的立體 (2通道) 數據流，畫面大小為四個字節。
GetBuffer 寫入 *pu64QPCPosition 的性能計數器值不是從 QueryPerformanceCounter 函式取得的原始計數器值。 如果 t 是原始計數器值，而且 f 是從 QueryPerformanceFrequency 函式取得的頻率， GetBuffer 會計算性能計數器值，如下所示：
*pu64QPCPosition = 10,000,000。t/F
結果會以 100 奈秒單位表示。 如需 QueryPerformanceCounter 和 QueryPerformanceFrequency 的詳細資訊，請參閱 Windows SDK 檔。
如果目前沒有可用的新封包，方法會設定 *pNumFramesToRead = 0，並傳回狀態代碼AUDCLNT_S_BUFFER_EMPTY。 在此情況下，方法不會寫入 ppData、 pu64DevicePosition 和 pu64QPCPosition 參數所指向的變數。
客戶端應該避免 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 方法的程式代碼範例，請參閱擷取 Stream。
規格需求
| 需求 | 值 |
|---|---|
| 最低支援的用戶端 | Windows Vista [傳統型應用程式 |UWP 應用程式] |
| 最低支援的伺服器 | Windows Server 2008 [傳統型應用程式 |UWP 應用程式] |
| 目標平台 | Windows |
| 標頭 | audioclient.h |
另請參閱
意見反應
即將登場：在 2024 年，我們將逐步淘汰 GitHub 問題作為內容的意見反應機制，並將它取代為新的意見反應系統。 如需詳細資訊，請參閱：https://aka.ms/ContentUserFeedback。
提交並檢視相關的意見反應