IAudioClient3：：InitializeSharedAudioStream 方法 (audioclient.h)

  • 發行項

使用指定的週期性，初始化共享數據流。

語法

HRESULT InitializeSharedAudioStream(
  [in]           DWORD              StreamFlags,
  [in]           UINT32             PeriodInFrames,
  [in]           const WAVEFORMATEX *pFormat,
  [in, optional] LPCGUID            AudioSessionGuid
);

參數

[in] StreamFlags

類型： DWORD

用來控制數據流建立的旗標。 用戶端應將此參數設定為0，或設定為一或多個支援的 AUDCLNT_STREAMFLAGS_XXX常數 或 AUDCLNT_SESSIONFLAGS_XXX常數位 OR。 使用此方法時，此參數支援的 AUDCLNT_STREAMFLAGS_XXX常數 為：

  • AUDCLNT_STREAMFLAGS_EVENTCALLBACK

[in] PeriodInFrames

類型： UINT32

用戶端要求的週期性。 這個值必須是 pFundamentalPeriodInFrames 參數中傳回至 IAudioClient3：：GetSharedModeEnginePeriod 中傳回之值的整數倍數。 PeriodInFrames 也必須大於或等於 pMinPeriodInFrames 中傳回的值，且小於或等於 pMaxPeriodInFrames 中傳回的值。

[in] pFormat

類型： const 顯示X*

格式描述元的指標。 這個參數必須指向一個類型為「顯示」或「是否為」的「有效格式描述元」，或是「顯示」。」 如需詳細資訊，請參閱 IAudioClient：：Initialize 的一節。

[in, optional] AudioSessionGuid

類型： LPCGUID

會話 GUID 的指標。 此參數指向 GUID 值，識別數據流所屬的音訊會話。 如果 GUID 識別先前已開啟的工作階段，方法會將數據流新增至該工作階段。 如果 GUID 無法識別現有的工作階段，方法會開啟新的工作階段，並將資料流新增至該工作階段。 數據流會在其存留期內維持相同會話的成員。 將此參數設定為 NULL 相當於將指標傳遞至GUID_NULL值。

傳回值

類型： HRESULT

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

傳回碼 Description
AUDCLNT_E_ALREADY_INITIALIZED
 IAudioClient 對象已經初始化。
AUDCLNT_E_WRONG_ENDPOINT_TYPE
 已設定AUDCLNT_STREAMFLAGS_LOOPBACK旗標，但端點裝置是擷取裝置，而不是轉譯裝置。
AUDCLNT_E_CPUUSAGE_EXCEEDED
 表示進程傳遞持續時間超過CPU使用量上限。 音訊引擎會藉由維護進程傳遞持續時間超過CPU使用量上限的次數，來追蹤CPU使用量。 最大 CPU 使用量會計算為引擎週期性的百分比。 百分比值是系統 CPU 節流值， (介於 10% 和 90% ) 的範圍內。 如果找不到此值，則會使用預設值 40% 來計算最大 CPU 使用量。
AUDCLNT_E_DEVICE_INVALIDATED
 音訊端點裝置已解除叢集，或音訊硬體或相關聯的硬體資源已重新設定、停用、移除或無法使用。
AUDCLNT_E_DEVICE_IN_USE
 端點裝置已在使用中。 裝置正以獨佔模式使用，或裝置正用於共用模式，而呼叫端要求以獨佔模式使用裝置。
AUDCLNT_E_ENGINE_FORMAT_LOCKED
 呼叫 IAudioClient2：：SetClientProperties 時指定的用戶端AUDCLNT_STREAMOPTIONS_MATCH_FORMAT，但音訊引擎的格式已由另一個客戶端鎖定。 在此情況下，您可以呼叫 IAudioClient2：：SetClientProperties ，而不指定比對格式選項，然後使用音訊引擎的目前格式。
AUDCLNT_E_ENGINE_PERIODICITY_LOCKED
 呼叫 IAudioClient2：：SetClientProperties 時指定的用戶端AUDCLNT_STREAMOPTIONS_MATCH_FORMAT，但音訊引擎的週期性已由另一個客戶端鎖定。 在此情況下，您可以呼叫 IAudioClient2：：SetClientProperties 而不指定比對格式選項，然後使用音訊引擎的目前週期性。
AUDCLNT_E_ENDPOINT_CREATE_FAILED
 方法無法建立轉譯或擷取裝置的音訊端點。 如果音訊端點裝置已解除叢集，或音訊硬體或相關聯的硬體資源已重新設定、停用、移除，或無法供使用，就會發生這種情況。
AUDCLNT_E_INVALID_DEVICE_PERIOD
 表示以 PeriodInFrames 指定的要求裝置期間不是音訊引擎基本週期的整數倍數、比引擎的最小期間短，或比引擎的最大期間長。 呼叫 IAudioClient3：：GetSharedModeEnginePeriod，以取得引擎支援的週期性值。
AUDCLNT_E_UNSUPPORTED_FORMAT
 音訊引擎 (共用模式) 或音訊端點裝置 (獨佔模式) 不支援指定的格式。
AUDCLNT_E_SERVICE_NOT_RUNNING
 Windows 音訊服務未執行。
E_POINTER
 參數 pFormat 為 NULL。
E_INVALIDARG
 參數 pFormat 指向無效的格式描述;或已設定AUDCLNT_STREAMFLAGS_LOOPBACK旗標，但 ShareMode 不等於 AUDCLNT_SHAREMODE_SHARED;或已設定AUDCLNT_STREAMFLAGS_CROSSPROCESS旗標，但 ShareMode 等於 AUDCLNT_SHAREMODE_EXCLUSIVE。

先前呼叫 SetClientProperties 時，已針對音訊/轉譯數據流使用無效的類別。
E_OUTOFMEMORY
 記憶體不足。

備註

不同於 IAudioClient：：Initialize，這個方法不允許您指定緩衝區大小。 緩衝區大小是根據 PeriodInFrames 參數所要求的週期性來計算。 用戶端應用程式必須負責確保音訊樣本會及時傳入和移出緩衝區。

音訊客戶端應該藉由呼叫 IAudioClient3：：GetSharedModeEnginePeriod 來檢查 PeriodInFrames 參數的允許值。 PeriodInFrames 的值必須是 pFundamentalPeriodInFrames 參數中所傳回值的整數倍數。 PeriodInFrames 也必須大於或等於 pMinPeriodInFrames 中傳回的值，且小於或等於 pMaxPeriodInFrames 的值。

例如，針對 44100 kHz 格式， GetSharedModeEnginePeriod 可能會傳回：

  • pDefaultPeriodInFrames = 448 個畫面格， (大約 10.16 毫秒)

  • pFundamentalPeriodInFrames = 4 個畫面格， (大約 0.09 毫秒)

  • pMinPeriodInFrames = 48 個畫面格， (大約 1.09 毫秒)

  • pMaxPeriodInFrames = 448 個畫面格， (與預設)

PeriodInFrames 參數的 Allowed values to InitializeSharedAudioStream 會包含 48 和 448。 它們也會包含 96 和 128 之類的專案。

它們不包含 4 個 (小於允許的最小值) 或 98 (，這不是基本) 的倍數，或大於允許值上限的 1000 () 。

規格需求

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

另請參閱

IAudioClient

IAudioClient2

IAudioClient3