IPerChannelDbLevel::SetLevel method (devicetopology.h)

The SetLevel method sets the volume level, in decibels, of the specified channel.

Syntax

HRESULT SetLevel(
  [in] UINT    nChannel,
  [in] float   fLevelDB,
  [in] LPCGUID pguidEventContext
);

Parameters

[in] nChannel

The number of the selected channel. If the audio stream has N channels, the channels are numbered from 0 to N– 1. To get the number of channels in the stream, call the IPerChannelDbLevel::GetChannelCount method.

[in] fLevelDB

The new volume level in decibels. A positive value represents gain, and a negative value represents attenuation.

[in] pguidEventContext

Context value for the IControlChangeNotify::OnNotify method. This parameter points to an event-context GUID. If the SetLevel call changes the state of the level control, all clients that have registered IControlChangeNotify interfaces with that control 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 control-change event. If the caller supplies a NULL pointer for this parameter, the client's notification method receives a NULL context pointer.

Return value

If the method succeeds, it returns S_OK. If it fails, possible return codes include, but are not limited to, the values shown in the following table.

Remarks

If the caller specifies a value for fLevelDB that is an exact stepping value, the SetLevel method completes successfully. A subsequent call to the IPerChannelDbLevel::GetLevel method will return either the value that was set, or one of the following values:

• If the set value was below the minimum, the GetLevel method returns the minimum value.
• If the set value was above the maximum, the GetLevel method returns the maximum value.
• If the set value was between two stepping values, the GetLevel method returns a value that could be the next stepping value above or the stepping value below the set value; the relative distances from the set value to the neighboring stepping values is unimportant. The value that the GetLevel method returns is whichever value has more of an impact on the signal path.

Requirements

See also

IPerChannelDbLevel Interface

IPerChannelDbLevel::GetChannelCount

IPerChannelDbLevel::GetLevel

IPerChannelDbLevel::GetLevelRange