IAudioSessionControl::RegisterAudioSessionNotification-Methode (audiopolicy.h)

  • Artikel

Die RegisterAudioSessionNotification-Methode registriert den Client, um Benachrichtigungen über Sitzungsereignisse zu erhalten, einschließlich Änderungen im Streamstatus.

Syntax

HRESULT RegisterAudioSessionNotification(
  [in] IAudioSessionEvents *NewNotifications
);

Parameter

[in] NewNotifications

Zeiger auf eine vom Client implementierte IAudioSessionEvents-Schnittstelle . Wenn die Methode erfolgreich ist, ruft sie die AddRef-Methode auf der IAudioSessionEvents-Schnittstelle des Clients auf.

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 Parameter NewNotifications 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

Diese Methode übergibt eine vom Client implementierte IAudioSessionEvents-Schnittstelle an den Sitzungs-Manager . Nach einem erfolgreichen Aufruf dieser Methode ruft der Sitzungs-Manager die Methoden in der IAudioSessionEvents-Schnittstelle auf, um den Client über verschiedene Sitzungsereignisse zu benachrichtigen. Mit diesen Methoden empfängt der Client Benachrichtigungen zu den folgenden sitzungsbezogenen Ereignissen:

  • Änderung des Anzeigenamens
  • Änderungen der Lautstärkeebene
  • Sitzungsstatusänderungen (inaktiv in aktiv oder aktiv zu inaktiv)
  • Gruppieren von Parameteränderungen
  • Trennen des Clients von der Sitzung (verursacht durch entfernen des Audioendpunktgeräts, Herunterfahren des Sitzungs-Managers oder Ändern des Streamformats durch den Benutzer)
Wenn Benachrichtigungen nicht mehr benötigt werden, kann der Client die IAudioSessionControl::UnregisterAudioSessionNotification-Methode aufrufen, um die Benachrichtigungen zu beenden.

Bevor der Client seinen endgültigen Verweis auf die IAudioSessionEvents-Schnittstelle freigibt, sollte er UnregisterAudioSessionNotification aufrufen, um die Registrierung der Schnittstelle aufzuheben. Andernfalls werden die Ressourcen der Objekte IAudioSessionEvents und IAudioSessionControl von der Anwendung verloren. Beachten Sie, dass RegisterAudioSessionNotification die IAudioSessionEvents::AddRef-Methode des Clients aufruft, und UnregisterAudioSessionNotification die IAudioSessionEvents::Release-Methode aufruft. Wenn der Client fehlert, indem er seinen Verweis auf die IAudioSessionEvents-Schnittstelle freigibt, bevor UnregisterAudioSessionNotification aufgerufen wird, gibt der Sitzungs-Manager seinen Verweis auf die IAudioSessionEvents-Schnittstelle nie frei. Eine schlecht gestaltete IAudioSessionEvents-Implementierung kann beispielsweise UnregisterAudioSessionNotification vom Destruktor für das IAudioSessionEvents-Objekt aufrufen. In diesem Fall ruft der Client UnregisterAudioSessionNotification erst auf, wenn der Sitzungs-Manager seinen Verweis auf die IAudioSessionEvents-Schnittstelle freigegeben hat, und der Sitzungs-Manager gibt seinen Verweis auf die IAudioSessionEvents-Schnittstelle erst frei, wenn der Client UnregisterAudioSessionNotification aufruft. Weitere Informationen zu den Methoden AddRef und Release finden Sie in der Windows SDK-Dokumentation zur IUnknown-Schnittstelle .

Darüber hinaus sollte der Client UnregisterAudioSessionNotification aufrufen, bevor alle Verweise auf die Objekte IAudioSessionControl und IAudioSessionManager freigegeben werden. Sofern der Client keinen Verweis auf mindestens eines dieser beiden Objekte beibehält, gibt der Sitzungs-Manager den Speicher aus, den er für die Registrierungsinformationen zugewiesen hat. Nach der Registrierung einer Benachrichtigungsschnittstelle empfängt der Client Benachrichtigungen nur so lange, wie mindestens eines dieser beiden Objekte vorhanden ist.

Ein Codebeispiel, das die RegisterAudioSessionNotification-Methode aufruft, finden Sie unter Audioereignisse für Legacy-Audioanwendungen.

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::UnregisterAudioSessionNotification

IAudioSessionEvents-Schnittstelle

IAudioSessionManager