共用方式為

IAudioClock：：GetPosition 方法 (audioclient.h)

  • 發行項

GetPosition 方法會取得目前的裝置位置。

語法

HRESULT GetPosition(
  [out] UINT64 *pu64Position,
  [out] UINT64 *pu64QPCPosition
);

參數

[out] pu64Position

方法寫入裝置位置的 UINT64 變數指標。 裝置位置是從數據流開頭到數據流中目前位置的位移。 不過，未定義這個位移的單位-裝置位置值只與 IAudioClock：：GetFrequency 方法所報告的頻率有關。 如需詳細資訊，請參閱＜備註＞。

[out] pu64QPCPosition

UINT64 變數的指標，此方法會在音訊端點裝置讀取裝置位置時寫入性能計數器的值， (*pu64Position) 回應 GetPosition 呼叫。 方法會將計數器值轉換成 100 奈秒的時間單位，再將它寫入 *pu64QPCPosition。 如果用戶端不需要性能計數器值，這個參數可以是 NULL 。

傳回值

如果方法成功並取得位置的精確讀數，則會傳回S_OK。 如果方法成功，但呼叫的持續時間夠長，足以從位置讀取的精確度減去，則方法會傳回S_FALSE。 如果失敗，可能的傳回碼包括，但不限於下表所示的值。

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

備註

轉譯或擷取需要根據數據流目前播放或記錄位置公開時鐘的用戶端，可以使用這個方法來衍生該時鐘。

這個方法會擷取兩個相互關聯的數據流位置值：

  • 裝置位置。 用戶端會透過輸出參數 pu64Position 取得裝置位置。 這是目前透過喇叭播放的範例串流位置， (轉譯數據流) ，或透過麥克風錄製 (擷取數據流) 。
  • 性能計數器。 用戶端會透過輸出參數 pu64QPCPosition 取得性能計數器。 這是在音頻端點裝置錄製數據流位置 (*pu64Position) 時呼叫 QueryPerformanceCounter 函式取得的計數器值。 請注意， GetPosition 會將計數器值轉換為 100 奈秒的時間單位。
除非裝置與 IAudioClock：：GetFrequency 方法所報告的裝置頻率結合，否則裝置位置沒有意義。 原因是不同數據流的裝置位置表示單位可能會根據因素而有所不同，例如數據流是以共用模式或獨佔模式開啟。 不過，從 GetFrequency 取得的頻率 f 一律是以與裝置位置 p 相容的單位表示。 因此，以秒為單位的數據流相對位移一律可以計算為 p/f。

裝置位置是數據流相對位移。 也就是說，它會指定為數據流開頭的位移。 裝置位置可視為理想化緩衝區的位移，其中包含整個數據流，且從頭到尾連續。

假設在 GetPosition 呼叫時裝置位置和性能計數器，用戶端可以藉由呼叫 QueryPerformanceCounter 來取得目前的性能計數器，根據計數器在記錄原始裝置位置之後的進階程度，提供更及時的裝置位置估計。 用戶端可以呼叫 QueryPerformanceFrequency 函式，以判斷遞增計數器的時鐘頻率。 在比較從 QueryPerformanceCounter 取得的原始計數器值與由 GetPosition 寫入 *pu64QPCPosition 的值之前，請將原始計數器值轉換為 100 奈秒的時間單位，如下所示：

  1. 將原始計數器值乘以 10,000,000。
  2. 將結果除以從 QueryPerformanceFrequency 取得的計數器頻率。
如需 QueryPerformanceCounter 和 QueryPerformanceFrequency 的詳細資訊，請參閱 Windows SDK 檔。

緊接在建立新數據流之後，裝置位置為 0。 在呼叫 IAudioClient：：Start 方法之後，裝置位置會以統一速率遞增。 IAudioClient：：Stop 方法會凍結裝置位置，而後續的 [開始] 呼叫會導致裝置位置在停止呼叫時繼續從其值遞增。 呼叫 IAudioClient：：Reset，只有在數據流停止時才會發生，會將裝置位置重設為 0。

當新的或重設轉譯數據流一開始執行時，其裝置位置可能會維持 0 毫秒，直到音訊數據有時間從端點緩衝區傳播到轉譯端點裝置為止。 當數據開始透過裝置播放時，裝置位置會從 0 變更為非零值。

後續裝置讀數會以單調方式增加。 雖然裝置位置可能不會在兩個連續讀數之間變更，但裝置位置永遠不會從一個讀數減少到下一個讀數。

pu64Position 參數必須是有效的非 NULL 指標，否則方法將會失敗，並傳回錯誤碼E_POINTER。

位置測量偶爾可能會因間歇性高優先順序事件而延遲。 這些事件可能與音訊無關。 如果是獨佔模式數據流，如果方法成功，但呼叫的持續時間夠長，足以從報告位置的精確度減去，則方法可以傳回S_FALSE，而不是傳回S_OK。 發生這種情況時，呼叫端可以選擇再次呼叫 方法，以嘗試擷取更精確的位置 (，如傳回值所指示S_OK) 。 不過，呼叫端應該避免在方法一致傳回S_FALSE的事件中，在無限迴圈中執行這項測試。

規格需求

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

另請參閱

IAudioClient：：Reset

IAudioClient：：Start

IAudioClient：：Stop

IAudioClock 介面

IAudioClock：：GetFrequency