Método IAudioSessionControl::SetDisplayName (audiopolicy.h)

O método SetDisplayName atribui um nome de exibição à sessão atual.

Sintaxe

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

Parâmetros

[in] Value

Ponteiro para uma cadeia de caracteres largos terminada em nulo que contém o nome de exibição da sessão.

[in] EventContext

Ponteiro para o GUID de contexto de evento. Se uma chamada para esse método gerar um evento de alteração de nome, o gerenciador de sessão enviará notificações a todos os clientes que registraram interfaces IAudioSessionEvents com o gerenciador de sessão. O gerenciador de sessão inclui o valor do ponteiro EventContext com cada notificação. Ao receber uma notificação, um cliente pode determinar se ele ou outro cliente é a origem do evento inspecionando o valor EventContext . Esse esquema depende do cliente selecionar um valor para esse parâmetro exclusivo entre todos os clientes na sessão. Se o chamador fornecer um ponteiro NULL para esse parâmetro, o método de notificação do cliente receberá um ponteiro de contexto NULL .

Retornar valor

Se o método for bem-sucedido, retornará S_OK. Se falhar, os códigos de retorno possíveis incluem, mas não se limitam a, os valores mostrados na tabela a seguir.

Código de retorno	Descrição
E_POINTER	Valor do parâmetro é NULL.
AUDCLNT_E_DEVICE_INVALIDATED	O dispositivo de ponto de extremidade de áudio foi desconectado ou o hardware de áudio ou os recursos de hardware associados foram reconfigurados, desabilitados, removidos ou não estão disponíveis para uso.
AUDCLNT_E_SERVICE_NOT_RUNNING	O serviço de áudio do Windows não está em execução.

Comentários

No Windows Vista, o programa fornecido pelo sistema, Sndvol.exe, usa o nome de exibição para rotular o controle de volume para a sessão. Se o cliente não chamar SetDisplayName para atribuir um nome de exibição à sessão, o programa Sndvol usará um nome padrão gerado automaticamente para rotular a sessão. O nome padrão incorpora informações como o título da janela ou o recurso de versão do aplicativo de áudio.

Se um cliente tiver mais de uma sessão ativa, os nomes de exibição especificados pelo cliente serão especialmente úteis para distinguir entre os controles de volume para as várias sessões.

No caso de uma sessão entre processos, a sessão não tem informações de identificação, como um nome de aplicativo ou ID de processo, da qual gerar um nome de exibição padrão. Portanto, o cliente deve chamar SetDisplayName para evitar exibir um nome de exibição padrão sem sentido.

O nome de exibição não persiste além do tempo de vida do objeto IAudioSessionControl . Assim, depois que todas as referências ao objeto forem lançadas, uma versão posteriormente criada do objeto (com o mesmo aplicativo, o mesmo GUID de sessão e o mesmo dispositivo de ponto de extremidade) terá novamente um nome de exibição padrão gerado automaticamente até que o cliente chame SetDisplayName.

O cliente pode recuperar o nome de exibição da sessão chamando o método IAudioSessionControl::GetDisplayName .

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows Vista [aplicativos da área de trabalho | Aplicativos UWP]
Servidor mínimo com suporte	Windows Server 2008 [aplicativos da área de trabalho | Aplicativos UWP]
Plataforma de Destino	Windows
Cabeçalho	audiopolicy.h

Confira também

IAudioSessionControl Interface

IAudioSessionControl::GetDisplayName

IAudioSessionEvents Interface