2 * Copyright (c) 2006-2009 Nokia Corporation and/or its subsidiary(-ies).
4 * This component and the accompanying materials are made available
5 * under the terms of "Eclipse Public License v1.0"
6 * which accompanies this distribution, and is available
7 * at the URL "http://www.eclipse.org/legal/epl-v10.html".
9 * Initial Contributors:
10 * Nokia Corporation - initial contribution.
27 #ifndef MAUDIOGAINCONTROL_H
28 #define MAUDIOGAINCONTROL_H
32 #include <a3f/a3fbase.h>
33 #include <a3f/maudioprocessingunit.h>
35 class MAudioGainControlObserver;
39 * Interface to gain control processing unit.
41 * Gain control is used for controlling volume and gain related settings of an audio stream.
43 class MAudioGainControl
48 * Returns the maximum gain the device supports.
50 * The maximum gain value depends on the setup of the stream.
52 * this is the maximum gain value which can be passed to SetGain().
53 * @param aMaxGain On return, contains the maximum gain value, provided that the returned error code is KErrNone.
54 * @return An error code. KErrNone if the maximum gain value is available, otherwise one of the system wide error codes.
56 virtual TInt GetMaxGain(TInt& aMaxGain) const= 0 ;
59 * Returns the maximum ramp time that is supported for the associated stream.
61 * The maximum ramp time may be different in playback and recording modes,
62 * so the value should be checked before setting the ramptime. this function
63 * also does not take into account any possible ongoing ramp.
65 * this is the maximum ramp time value which can be passed to SetGain().
66 * @param aMaxRampTime On return contains the maximum ramp time.
67 * The value is platform and stream setup dependent but is always greater than or equal to zero.
68 * @return An error code. KErrNone on success, otherwise one of the system wide error codes.
70 virtual TInt GetMaxRampTime(TTimeIntervalMicroSeconds& aMaxRampTime) const= 0;
73 * Requests changes to the audio gain on a channel-by-channel basis.
75 * Note that the values for each channel are independent of each other.
76 * The call is asynchronous in nature, resulting in a GainChanged()
77 * callback, and the request is only applied following a successful
79 * The callback signals the receipt of the SetGain() call from the
80 * underlying adaptation, and not (say) the completion of a ramp operation.
81 * The actual gains will only change once the associated Audio Stream becomes EActive.
82 * If the associated Audio Stream is already EActive
83 * then the change will start immediately following the next successful Commit() cycle.
84 * MMRC may choose to modify or ignore the requested gains.
86 * @param aChannels Contains the channels for which the gain should be set and the gain value for those channels.
87 * @param aRampOperation How aRampDuration is to be interpreted.(see below)
88 * @param aRampDuration Duration in microseconds.
89 * @return KErrNone if initially successful.
90 * KErrNotSupported if the SetGain() call referred to non-existent channels.
91 * KErrArgument if aGain of less than 0 or larger than max gain, the same channel is specified multiple times,
92 * or aRampDuration is less than 0 or greater than max ramp duration.
93 * KErrA3fUnsupportedRamp if the ramp operation requested is not supported, or the Uid value supplies is unknown.
94 * Other system-wide error codes are also possible.
95 * These errors could instead by returned as part of the subsequent GainChanged() callback – depending on the a3f adaptation.
96 * Also note: the requested parameters are specific to the associated stream.
97 * If more than one stream is concurrently active to the same device,
98 * it is up to the adaptation to arrange both the device gains the mixer and splitter gains to achieve a similar effect to the several streams being played through separate devices and mixed post-amplification.
100 virtual TInt SetGain(RArray<TAudioChannelGain>& aChannels, TUid aRampOperation, const TTimeIntervalMicroSeconds& aRampDuration)=0;
103 * Sets the audio channel gain.
105 * By default all channels are set to use same gain value. Note that the
106 * values for each channel are independent of each other, meaning that
107 * they only control the gain level on which the particular channel is
108 * being used and there is no limitation requiring the sum of all channels to be 100.
110 * The gain values will be applied once the associated stream is active.
111 * if the stream is active while this function is called, then the values
112 * are applied immediately.
114 * @param aChannels Contains the channels for which the gain should be set and the gain value for those channels.
115 * @return An error code. KErrNone on success.
116 * KErrNotSupported if gain for unsupported channels is tried to be set.
117 * KErrArgument if a value of less than 0 or larger than max gain is tried to be set as gain.
118 * Other system wide error codes are also possible.
120 virtual TInt SetGain(RArray<TAudioChannelGain>& aChannels)=0;
123 * Returns channel specific gain settings.
125 * @param aChannels On return contains current gain settings for each audio channel.
126 * @return An error code. KErrNone on success.
127 * KErrArgument if the array passed in as a parameter is not empty.
128 * KErrOutOfMemory in case of memory exhaustion.
129 * Other system wide error codes are also possible.
131 virtual TInt GetGain(RArray<TAudioChannelGain>& aChannels) const= 0;
134 * Registers an observer for receiving callbacks.
136 * @param aObserver a reference to the observer to register.
137 * @return An error code. KErrNone on success, otherwise one of the system wide error codes.
139 virtual TInt RegisterAudioGainControlObserver(MAudioGainControlObserver& aObserver)=0;
142 * Unregisters an observer.
144 * @param aObserver a reference to observer to unregister.
146 virtual void UnregisterAudioGainControlObserver(MAudioGainControlObserver& aObserver)=0;
150 #endif // MAUDIOGAINCONTROL_H