共用方式為

IMMDeviceEnumerator：：GetDefaultAudioEndpoint 方法 (mmdeviceapi.h)

  • 發行項

GetDefaultAudioEndpoint 方法會擷取指定數據流方向和角色的預設音訊端點。

語法

HRESULT GetDefaultAudioEndpoint(
  [in]  EDataFlow dataFlow,
  [in]  ERole     role,
  [out] IMMDevice **ppEndpoint
);

參數

[in] dataFlow

端點裝置的數據流方向。 呼叫端應該將此參數設定為下列兩個 EDataFlow 列舉值的其中一個：

eRender

eCapture

轉譯裝置的數據流方向為 eRender。 擷取裝置的數據流方向為 eCapture。

[in] role

端點裝置的角色。 呼叫端應該將此參數設定為下列其中一個 ERole 列舉值：

eConsole

eMultimedia

eCommunications

如需詳細資訊，請參閱＜備註＞。

[out] ppEndpoint

指標變數的指標，此方法會寫入預設音訊端點裝置之端點物件 之 IMMDevice 介面的位址。 透過這個方法，呼叫端會取得介面的計數參考。 呼叫端負責藉由呼叫介面的 Release 方法，在不再需要介面時釋出介面。 如果 GetDefaultAudioEndpoint 呼叫失敗， *ppDevice 為 NULL。

傳回值

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

傳回碼 Description
E_POINTER
 參數 ppDevice 為 NULL。
E_INVALIDARG
 參數 數據流 或 角色 超出範圍。
E_NOTFOUND
 沒有可用的裝置。
E_OUTOFMEMORY
 記憶體不足。

備註

注意

在 Windows Vista 中，MMDevice API 支援 裝置角色， 但系統提供的使用者介面程式則不支援。 Windows Vista 中的使用者介面可讓使用者選取用於轉譯的預設音訊裝置，以及用於擷取的預設音訊裝置。 當使用者變更預設轉譯或擷取裝置時，系統會將 eConsole、eMultimedia 和 eCommunications) 的所有三個裝置 (角色指派給該裝置。 因此， GetDefaultAudioEndpoint 一律會選取預設轉譯或擷取裝置，不論 角色 參數所指出的角色為何。 在未來的 Windows 版本中，使用者介面可能會讓使用者將個別角色指派給不同的裝置。 在此情況下， GetDefaultAudioEndpoint 的轉譯或擷取裝置選取可能會取決於 角色 參數。 因此，開發為在 Windows Vista 中執行的音訊應用程式行為可能會在未來版本的 Windows 中執行時變更。 如需詳細資訊，請參閱 Windows Vista 中的裝置角色。

此方法會擷取指定數據流方向的預設端點裝置， (轉譯或擷取) 和角色。 例如，用戶端可以透過進行下列呼叫來取得預設主控台播放裝置：


  hr = pDevEnum->GetDefaultAudioEndpoint(
                   eRender, eConsole, &pDeviceOut);

在上述代碼段中，變數 hr 的類型為 HRESULT，pDevEnum 是 IMMDeviceEnumerator 介面的指標，而 pDeviceOut 是 IMMDevice 介面的指標。

Windows 系統可能包含一些音訊端點裝置的組合，例如桌面喇叭、高逼真度耳機、桌面麥克風、具有喇叭和麥克風的頭戴式裝置，以及高精確度的多通道喇叭。 用戶可以將適當的角色指派給裝置。 例如，管理語音通訊數據流的應用程式可以呼叫 GetDefaultAudioEndpoint 來識別該角色的指定轉譯和擷取裝置。

如果只有單一轉譯或擷取裝置可用，系統一律會將這三個轉譯或擷取角色指派給該裝置。 如果方法找不到指定角色的轉譯或擷取裝置，這表示完全無法使用轉譯或擷取裝置。 如果沒有可用的裝置，此方法會設定 *ppEndpoint = NULL 並傳回ERROR_NOT_FOUND。

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

規格需求

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

另請參閱

IMMDevice 介面

IMMDeviceEnumerator 介面