Метод IAudioSessionControl::SetDisplayName (audiopolicy.h)

Статья
08/22/2023

Метод SetDisplayName назначает отображаемое имя текущему сеансу.

Синтаксис

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

Параметры

[in] Value

Указатель на строку расширенных символов, завершающуюся null, которая содержит отображаемое имя сеанса.

[in] EventContext

Указатель на GUID контекста события. Если вызов этого метода создает событие изменения имени, диспетчер сеансов отправляет уведомления всем клиентам, которые зарегистрировали интерфейсы IAudioSessionEvents с диспетчером сеансов. Диспетчер сеансов включает значение указателя EventContext с каждым уведомлением. Получив уведомление, клиент может определить, является ли он или другой клиент источником события, проверив значение EventContext . Эта схема зависит от того, выбирает клиент значение для этого параметра, которое является уникальным среди всех клиентов в сеансе. Если вызывающий объект предоставляет указатель NULL для этого параметра, метод уведомления клиента получает указатель контекста NULL .

Возвращаемое значение

Если метод завершается успешно, возвращает значение S_OK. В случае сбоя возможные коды возврата включают, помимо прочего, значения, показанные в следующей таблице.

Код возврата	Описание
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
Header	audiopolicy.h

См. также раздел

Интерфейс IAudioSessionControl

IAudioSessionControl::GetDisplayName

Интерфейс IAudioSessionEvents

Поделиться через