IAudioEndpointVolume::SetChannelVolumeLevelScalar method (endpointvolume.h)
The SetChannelVolumeLevelScalar method sets the normalized, audio-tapered volume level of the specified channel in the audio stream that enters or leaves the audio endpoint device.
Syntax
HRESULT SetChannelVolumeLevelScalar(
[in] UINT nChannel,
[in] float fLevel,
[in] LPCGUID pguidEventContext
);
Parameters
[in] nChannel
The channel number. If the audio stream contains n channels, the channels are numbered from 0 to n– 1. To obtain the number of channels, call the IAudioEndpointVolume::GetChannelCount method.
[in] fLevel
The volume level. The volume level is expressed as a normalized value in the range from 0.0 to 1.0.
[in] pguidEventContext
Context value for the IAudioEndpointVolumeCallback::OnNotify method. This parameter points to an event-context GUID. If the SetChannelVolumeLevelScalar call changes the volume level of the endpoint, all clients that have registered IAudioEndpointVolumeCallback interfaces with that endpoint will receive notifications. In its implementation of the OnNotify method, a client can inspect the event-context GUID to discover whether it or another client is the source of the volume-change event. If the caller supplies a NULL pointer for this parameter, the notification routine receives the context GUID value GUID_NULL.
Return value
If the method succeeds, it returns S_OK. If the method fails, possible return codes include, but are not limited to, the values shown in the following table.
| Return code | Description |
|---|---|
|
Parameter nChannel is greater than or equal to the number of channels in the stream; or parameter fLevel is outside the range from 0.0 to 1.0. |
|
Out of memory. |
Remarks
The volume level is normalized to the range from 0.0 to 1.0, where 0.0 is the minimum volume level and 1.0 is the maximum level. Within this range, the relationship of the normalized volume level to the attenuation of signal amplitude is described by a nonlinear, audio-tapered curve. Note that the shape of the curve might change in future versions of Windows. For more information about audio-tapered curves, see Audio-Tapered Volume Controls.
The normalized volume levels that are passed to this method are suitable to represent the positions of volume controls in application windows and on-screen displays.
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 | endpointvolume.h |
See also
IAudioEndpointVolume Interface
IAudioEndpointVolume::GetChannelCount