共用方式為

IAudioSessionControl：：SetDisplayName 方法 (audiopolicy.h)

  • 發行項

SetDisplayName 方法會將顯示名稱指派給目前的會話。

語法

HRESULT SetDisplayName(
  [in] LPCWSTR Value,
  [in] LPCGUID EventContext
);

參數

[in] Value

以 Null 結尾且寬字元字串的指標，其中包含工作階段的顯示名稱。

[in] EventContext

事件內容 GUID 的指標。 如果呼叫這個方法會產生名稱變更事件，會話管理員會傳送通知給已向會話管理員註冊 IAudioSessionEvents 介面的所有用戶端。 會話管理員會在每個通知中包含 EventContext 指標值。 收到通知時，用戶端可以藉由檢查 EventContext 值來判斷它或另一個用戶端是否為事件的來源。 此配置取決於客戶端選取這個參數的值，這個參數在會話中的所有客戶端之間是唯一的。 如果呼叫端提供此參數的 NULL 指標，則用戶端的通知方法會收到 NULL 內容指標。

傳回值

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

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

備註

在 Windows Vista 中，系統提供的程式 Sndvol.exe 會使用顯示名稱來標記會話的磁碟區控制件。 如果用戶端未呼叫 SetDisplayName 將顯示名稱指派給會話，Sndvol 程式會使用預設的自動產生名稱來標記會話。 默認名稱會納入資訊，例如音訊應用程式的視窗標題或版本資源。

如果用戶端有多個使用中的會話，則用戶端指定的顯示名稱特別有助於區分各種會話的磁碟區控制件。

在跨進程會話的情況下，會話沒有識別資訊，例如要從中產生預設顯示名稱的應用程式名稱或進程標識符。 因此，客戶端必須呼叫 SetDisplayName ，以避免顯示無意義的預設顯示名稱。

顯示名稱不會保存超過 IAudioSessionControl 物件的存留期。 因此，發行物件的所有參考之後，後續會使用相同的應用程式、相同的會話 GUID 和相同的端點裝置 (建立的物件版本，而相同的端點裝置) 會再次具有預設的自動產生顯示名稱，直到用戶端呼叫 SetDisplayName 為止。

用戶端可以藉由呼叫 IAudioSessionControl：：GetDisplayName 方法來擷取會話的顯示名稱。

規格需求

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

另請參閱

IAudioSessionControl 介面

IAudioSessionControl：：GetDisplayName

IAudioSessionEvents 介面