IAudioSessionEvents::OnSessionDisconnected method (audiopolicy.h)

The OnSessionDisconnected method notifies the client that the audio session has been disconnected.

Syntax

HRESULT OnSessionDisconnected(
  [in] AudioSessionDisconnectReason DisconnectReason
);

Parameters

[in] DisconnectReason

The reason that the audio session was disconnected. The caller sets this parameter to one of the AudioSessionDisconnectReason enumeration values shown in the following table.

Value Description
DisconnectReasonDeviceRemoval The user removed the audio endpoint device.
DisconnectReasonServerShutdown The Windows audio service has stopped.
DisconnectReasonFormatChanged The stream format changed for the device that the audio session is connected to.
DisconnectReasonSessionLogoff The user logged off the Windows Terminal Services (WTS) session that the audio session was running in.
DisconnectReasonSessionDisconnected The WTS session that the audio session was running in was disconnected.
DisconnectReasonExclusiveModeOverride The (shared-mode) audio session was disconnected to make the audio endpoint device available for an exclusive-mode connection.
 

For more information about WTS sessions, see the Windows SDK documentation.

Return value

If the method succeeds, it returns S_OK. If it fails, it returns an error code.

Remarks

When disconnecting a session, the session manager closes the streams that belong to that session and invalidates all outstanding requests for services on those streams. The client should respond to a disconnection by releasing all of its references to the IAudioClient interface for a closed stream and releasing all references to the service interfaces that it obtained previously through calls to the IAudioClient::GetService method.

Following disconnection, many of the methods in the WASAPI interfaces that are tied to closed streams in the disconnected session return error code AUDCLNT_E_DEVICE_INVALIDATED (for example, see IAudioClient::GetCurrentPadding). For information about recovering from this error, see Recovering from an Invalid-Device Error.

If the Windows audio service terminates unexpectedly, it does not have an opportunity to notify clients that it is shutting down. In that case, clients learn that the service has stopped when they call a method such as IAudioClient::GetCurrentPadding that discovers that the service is no longer running and fails with error code AUDCLNT_E_SERVICE_NOT_RUNNING.

A client cannot generate a session-disconnected event. The system is always the source of this type of event. Thus, unlike some other IAudioSessionEvents methods, this method does not have a context parameter.

For a code example that implements the methods in the IAudioSessionEvents interface, see Audio Session Events.

Requirements

Requirement Value
Minimum supported client Windows Vista [desktop apps | UWP apps]
Minimum supported server Windows Server 2008 [desktop apps | UWP apps]
Target Platform Windows
Header audiopolicy.h

See also

IAudioClient Interface

IAudioClient::GetService

IAudioSessionEvents Interface