Metodo IAudioSessionControl::SetDisplayName (audiopolicy.h)

Articolo
03/09/2024

Il metodo SetDisplayName assegna un nome visualizzato alla sessione corrente.

Sintassi

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

Parametri

[in] Value

Puntatore a una stringa di caratteri wide con terminazione Null contenente il nome visualizzato per la sessione.

[in] EventContext

Puntatore al GUID del contesto dell'evento. Se una chiamata a questo metodo genera un evento di modifica del nome, il gestore della sessione invia notifiche a tutti i client che hanno registrato interfacce IAudioSessionEvents con la gestione sessione. La gestione sessione include il valore del puntatore EventContext con ogni notifica. Dopo aver ricevuto una notifica, un client può determinare se è l'origine dell'evento o un altro client controllando il valore EventContext . Questo schema dipende dal client che seleziona un valore per questo parametro univoco tra tutti i client nella sessione. Se il chiamante fornisce un puntatore NULL per questo parametro, il metodo di notifica del client riceve un puntatore di contesto NULL .

Valore restituito

Se il metodo ha esito positivo, viene restituito S_OK. Se ha esito negativo, i possibili codici restituiti includono, ma non sono limitati, i valori illustrati nella tabella seguente.

Codice restituito	Descrizione
E_POINTER	Il valore del parametro è NULL.
AUDCLNT_E_DEVICE_INVALIDATED	Il dispositivo endpoint audio è stato scollegato oppure l'hardware audio o le risorse hardware associate sono state riconfigurate, disabilitate, rimosse o altrimenti non disponibili per l'uso.
AUDCLNT_E_SERVICE_NOT_RUNNING	Il servizio audio di Windows non è in esecuzione.

Commenti

In Windows Vista, il programma fornito dal sistema, Sndvol.exe, usa il nome visualizzato per etichettare il controllo volume per la sessione. Se il client non chiama SetDisplayName per assegnare un nome visualizzato alla sessione, il programma Sndvol usa un nome predefinito generato automaticamente per etichettare la sessione. Il nome predefinito incorpora informazioni quali il titolo della finestra o la risorsa della versione dell'applicazione audio.

Se un client ha più sessioni attive, i nomi visualizzati specificati dal client sono particolarmente utili per distinguere tra i controlli del volume per le varie sessioni.

Nel caso di una sessione tra processi, la sessione non dispone di informazioni di identificazione, ad esempio un nome applicazione o un ID processo, da cui generare un nome visualizzato predefinito. Pertanto, il client deve chiamare SetDisplayName per evitare di visualizzare un nome visualizzato predefinito senza significato.

Il nome visualizzato non persiste oltre la durata dell'oggetto IAudioSessionControl . Pertanto, dopo il rilascio di tutti i riferimenti all'oggetto, una versione creata successivamente dell'oggetto (con la stessa applicazione, lo stesso GUID di sessione e lo stesso dispositivo endpoint) avrà nuovamente un nome visualizzato predefinito, generato automaticamente fino a quando il client non chiama SetDisplayName.

Il client può recuperare il nome visualizzato per la sessione chiamando il metodo IAudioSessionControl::GetDisplayName .

Requisiti

Requisito	Valore
Client minimo supportato	Windows Vista [app desktop \| App UWP]
Server minimo supportato	Windows Server 2008 [app desktop \| App UWP]
Piattaforma di destinazione	Windows
Intestazione	audiopolicy.h

Vedi anche

Interfaccia IAudioSessionControl

IAudioSessionControl::GetDisplayName

Interfaccia IAudioSessionEvents

Share via