IAudioSessionControl::SetDisplayName-Methode (audiopolicy.h)

Die SetDisplayName-Methode weist der aktuellen Sitzung einen Anzeigenamen zu.

Syntax

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

Parameter

[in] Value

Zeiger auf eine mit NULL beendete breitzeichenige Zeichenfolge, die den Anzeigenamen für die Sitzung enthält.

[in] EventContext

Zeiger auf die Ereigniskontext-GUID. Wenn ein Aufruf dieser Methode ein Namensänderungsereignis generiert, sendet der Sitzungs-Manager Benachrichtigungen an alle Clients, die IAudioSessionEvents-Schnittstellen beim Sitzungs-Manager registriert haben. Der Sitzungs-Manager enthält den EventContext-Zeigerwert mit jeder Benachrichtigung. Beim Empfang einer Benachrichtigung kann ein Client feststellen, ob er oder ein anderer Client die Quelle des Ereignisses ist, indem er den EventContext-Wert überprüft. Dieses Schema hängt davon ab, dass der Client einen Wert für diesen Parameter auswählt, der für alle Clients in der Sitzung eindeutig ist. Wenn der Aufrufer einen NULL-Zeiger für diesen Parameter bereitstellt, empfängt die Benachrichtigungsmethode des Clients einen NULL-Kontextzeiger .

Rückgabewert

Wenn die Methode erfolgreich ist, wird S_OK zurückgegeben. Wenn ein Fehler auftritt, können mögliche Rückgabecodes die in der folgenden Tabelle gezeigten Werte umfassen, sind jedoch nicht darauf beschränkt.

Rückgabecode	Beschreibung
E_POINTER	Der Parameterwert ist NULL.
AUDCLNT_E_DEVICE_INVALIDATED	Das Audioendpunktgerät wurde getrennt, oder die Audiohardware oder die zugehörigen Hardwareressourcen wurden neu konfiguriert, deaktiviert, entfernt oder anderweitig für die Verwendung nicht verfügbar gemacht.
AUDCLNT_E_SERVICE_NOT_RUNNING	Der Windows-Audiodienst wird nicht ausgeführt.

Hinweise

In Windows Vista verwendet das vom System bereitgestellte Programm Sndvol.exe den Anzeigenamen, um die Lautstärkesteuerung für die Sitzung zu bezeichnen. Wenn der Client SetDisplayName nicht aufruft, um der Sitzung einen Anzeigenamen zuzuweisen, verwendet das Sndvol-Programm einen automatisch generierten Standardnamen, um die Sitzung zu bezeichnen. Der Standardname enthält Informationen wie den Fenstertitel oder die Versionsressource der Audioanwendung.

Wenn ein Client über mehr als eine aktive Sitzung verfügt, sind vom Client angegebene Anzeigenamen besonders hilfreich, um zwischen den Lautstärkesteuerelementen für die verschiedenen Sitzungen zu unterscheiden.

Im Fall einer prozessübergreifenden Sitzung enthält die Sitzung keine identifizierenden Informationen, z. B. einen Anwendungsnamen oder eine Prozess-ID, aus der ein Standardanzeigename generiert werden soll. Daher muss der Client SetDisplayName aufrufen, um zu vermeiden, dass ein bedeutungsloser Standardanzeigename angezeigt wird.

Der Anzeigename bleibt nicht über die Lebensdauer des IAudioSessionControl-Objekts hinaus erhalten. Nachdem also alle Verweise auf das Objekt freigegeben wurden, verfügt eine anschließend erstellte Version des Objekts (mit derselben Anwendung, derselben Sitzungs-GUID und demselben Endpunktgerät) erneut über einen standardmäßigen automatisch generierten Anzeigenamen, bis der Client SetDisplayName aufruft.

Der Client kann den Anzeigenamen für die Sitzung abrufen, indem er die IAudioSessionControl::GetDisplayName-Methode aufruft.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows Vista [Desktop-Apps | UWP-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2008 [Desktop-Apps | UWP-Apps]
Zielplattform	Windows
Kopfzeile	audiopolicy.h

Weitere Informationen

IAudioSessionControl-Schnittstelle

IAudioSessionControl::GetDisplayName

IAudioSessionEvents-Schnittstelle