Edit

IMMNotificationClient::OnDefaultDeviceChanged method (mmdeviceapi.h)

  • Article

The OnDefaultDeviceChanged method notifies the client that the default audio endpoint device for a particular device role has changed.

Syntax

HRESULT OnDefaultDeviceChanged(
  [in] EDataFlow flow,
  [in] ERole     role,
  [in] LPCWSTR   pwstrDefaultDeviceId
);

Parameters

[in] flow

The data-flow direction of the endpoint device. This parameter is set to one of the following EDataFlow enumeration values:

eRender

eCapture

The data-flow direction for a rendering device is eRender. The data-flow direction for a capture device is eCapture.

[in] role

The device role of the audio endpoint device. This parameter is set to one of the following ERole enumeration values:

eConsole

eMultimedia

eCommunications

[in] pwstrDefaultDeviceId

Pointer to the endpoint ID string that identifies the audio endpoint device. This parameter points to a null-terminated, wide-character string containing the endpoint ID. The string remains valid for the duration of the call. If the user has removed or disabled the default device for a particular role, and no other device is available to assume that role, then pwstrDefaultDevice is NULL.

Return value

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

Remarks

The three input parameters specify the data-flow direction, device role, and endpoint ID string of the new default audio endpoint device.

In Windows Vista, the MMDevice API supports device roles but the system-supplied user interface programs do not. The user interface in Windows Vista enables the user to select a default audio device for rendering and a default audio device for capture. When the user changes the default rendering or capture device, the system assigns all three device roles (eConsole, eMultimedia, and eCommunications) to the new device. Thus, when the user changes the default rendering or capture device, the system calls the client's OnDefaultDeviceChanged method three times—once for each of the three device roles.

In a future version of Windows, the user interface might enable the user to assign individual roles to different devices. In that case, if the user changes the assignment of only one or two device roles to a new rendering or capture device, the system will call the client's OnDefaultDeviceChanged method only once or twice (that is, one call per changed role). Depending on how the OnDefaultDeviceChanged method responds to role changes, the behavior of an audio application developed to run in Windows Vista might change when run in a future version of Windows. For more information, see Device Roles in Windows Vista.

For a code example that implements the OnDefaultDeviceChanged method, see Device Events.

Requirements

Requirement Value
Minimum supported client Windows Vista [desktop apps only]
Minimum supported server Windows Server 2008 [desktop apps only]
Target Platform Windows
Header mmdeviceapi.h

See also

IMMNotificationClient Interface