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

El método SetDisplayName asigna un nombre para mostrar a la sesión actual.

Sintaxis

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

Parámetros

[in] Value

Puntero a una cadena de caracteres anchos terminada en null que contiene el nombre para mostrar de la sesión.

[in] EventContext

Puntero al GUID del contexto de evento. Si una llamada a este método genera un evento de cambio de nombre, el administrador de sesiones envía notificaciones a todos los clientes que han registrado interfaces IAudioSessionEvents con el administrador de sesiones. El administrador de sesiones incluye el valor del puntero EventContext con cada notificación. Al recibir una notificación, un cliente puede determinar si es el origen del evento inspeccionando el valor eventContext . Este esquema depende del cliente que seleccione un valor para este parámetro que sea único entre todos los clientes de la sesión. Si el autor de la llamada proporciona un puntero NULL para este parámetro, el método de notificación del cliente recibe un puntero de contexto NULL .

Valor devuelto

Si el método se realiza correctamente, devuelve S_OK. Si se produce un error, los posibles códigos de retorno incluyen, pero no están limitados a, los valores que se muestran en la tabla siguiente.

Código devuelto	Descripción
E_POINTER	El valor del parámetro es NULL.
AUDCLNT_E_DEVICE_INVALIDATED	El dispositivo de punto de conexión de audio se ha desconectado o el hardware de audio o los recursos de hardware asociados se han reconfigurado, deshabilitado, quitado o no están disponibles para su uso.
AUDCLNT_E_SERVICE_NOT_RUNNING	El servicio de audio de Windows no se está ejecutando.

Comentarios

En Windows Vista, el programa proporcionado por el sistema, Sndvol.exe, usa el nombre para mostrar para etiquetar el control de volumen de la sesión. Si el cliente no llama a SetDisplayName para asignar un nombre para mostrar a la sesión, el programa Sndvol usa un nombre predeterminado generado automáticamente para etiquetar la sesión. El nombre predeterminado incorpora información como el título de la ventana o el recurso de versión de la aplicación de audio.

Si un cliente tiene más de una sesión activa, los nombres para mostrar especificados por el cliente son especialmente útiles para distinguir entre los controles de volumen de las distintas sesiones.

En el caso de una sesión entre procesos, la sesión no tiene información de identificación, como un nombre de aplicación o un identificador de proceso, desde el que generar un nombre para mostrar predeterminado. Por lo tanto, el cliente debe llamar a SetDisplayName para evitar mostrar un nombre para mostrar predeterminado sin significado.

El nombre para mostrar no persiste más allá de la duración del objeto IAudioSessionControl . Por lo tanto, una vez publicadas todas las referencias al objeto, una versión creada posteriormente del objeto (con la misma aplicación, el mismo GUID de sesión y el mismo dispositivo de punto de conexión) tendrá de nuevo un nombre para mostrar generado automáticamente hasta que el cliente llame a SetDisplayName.

El cliente puede recuperar el nombre para mostrar de la sesión llamando al método IAudioSessionControl::GetDisplayName .

Requisitos

Requisito	Value
Cliente mínimo compatible	Windows Vista [aplicaciones de escritorio | aplicaciones para UWP]
Servidor mínimo compatible	Windows Server 2008 [aplicaciones de escritorio | aplicaciones para UWP]
Plataforma de destino	Windows
Encabezado	audiopolicy.h

Consulte también

IAudioSessionControl (interfaz)

IAudioSessionControl::GetDisplayName

Interfaz IAudioSessionEvents