/*

* Copyright (c) 2006-2009 Nokia Corporation and/or its subsidiary(-ies).

* All rights reserved.

* This component and the accompanying materials are made available

* under the terms of "Eclipse Public License v1.0"

* which accompanies this distribution, and is available

* at the URL "http://www.eclipse.org/legal/epl-v10.html".

*

* Initial Contributors:

* Nokia Corporation - initial contribution.

*

* Contributors:

*

* Description:

*

*/

/**

 @file

 @publishedPartner

 @released

*/

#ifndef MAUDIOGAINCONTROL_H

#define MAUDIOGAINCONTROL_H

#include <e32base.h>

#include <f32file.h>

#include <a3f/a3fbase.h>

#include <a3f/maudioprocessingunit.h>

class MAudioGainControlObserver;

/**

 * Interface to gain control processing unit.

 *

 * Gain control is used for controlling volume and gain related settings of an audio stream.

 */

class MAudioGainControl

	{

	public:

	/** 

	* Returns the maximum gain the device supports.

	*

	* The maximum gain value depends on the setup of the stream.

	* 

	* this is the maximum gain value which can be passed to SetGain().

	* @param aMaxGain On return, contains the maximum gain value, provided that the returned error code is KErrNone.

	* @return An error code. KErrNone if the maximum gain value is available, otherwise one of the system wide error codes.

	*/

	virtual TInt GetMaxGain(TInt& aMaxGain) const= 0 ;

	/**

	* Returns the maximum ramp time that is supported for the associated stream.

	*

	* The maximum ramp time may be different in playback and recording modes,

	* so the value should be checked before setting the ramptime. this function

	* also does not take into account any possible ongoing ramp.

	* 

	* this is the maximum ramp time value which can be passed to SetGain().

	* @param aMaxRampTime On return contains the maximum ramp time.

	* The value is platform and stream setup dependent but is always greater than or equal to zero.

	* @return An error code. KErrNone on success, otherwise one of the system wide error codes.

	*/

	virtual TInt GetMaxRampTime(TTimeIntervalMicroSeconds& aMaxRampTime) const= 0;

	/**

	* Requests changes to the audio gain on a channel-by-channel basis. 

	* Note that the values for each channel are independent of each other. 

	* The call is asynchronous in nature, resulting in a GainChanged() 

	* callback, and the request is only applied following a successful 

	* Commit() cycle. 

	* The callback signals the receipt of the SetGain() call from the 

	* underlying adaptation, and not (say) the completion of a ramp operation. 

	* The actual gains will only change once the associated Audio Stream becomes EActive. 

	* If the associated Audio Stream is already EActive 

	* then the change will start immediately following the next successful Commit() cycle. 

	* MMRC may choose to modify or ignore the requested gains. 

	* @param aChannels	 Contains the channels for which the gain should be set and the gain value for those channels.

	* @param aRampOperation  How aRampDuration is to be interpreted.(see below)

	* @param aRampDuration Duration in microseconds.

	* @return KErrNone if initially successful.

	*         KErrNotSupported if the SetGain() call referred to non-existent channels.

	*         KErrArgument if aGain of less than 0 or larger than max gain, the same channel is specified multiple times, 

	*           or aRampDuration is less than 0 or greater than max ramp duration.

	*         KErrA3fUnsupportedRamp  if the ramp operation requested is not supported, or the Uid value supplies is unknown.

	* Other system-wide error codes are also possible.

	* These errors could instead by returned as part of the subsequent GainChanged() callback – depending on the a3f adaptation.

	* Also note: the requested parameters are specific to the associated stream. 

	* If more than one stream is concurrently active to the same device, 

	* 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.

	*/

	virtual TInt SetGain(RArray<TAudioChannelGain>& aChannels, TUid aRampOperation, const TTimeIntervalMicroSeconds& aRampDuration)=0;

	/**

	* Sets the audio channel gain.

	* 

	* By default all channels are set to use same gain value. Note that the

	* values for each channel are independent of each other, meaning that

	* they only control the gain level on which the particular channel is

	* being used and there is no limitation requiring the sum of all channels to be 100.

	* 

	* The gain values will be applied once the associated stream is active.

	* if the stream is active while this function is called, then the values

	* are applied immediately.

	*

	* @param aChannels Contains the channels for which the gain should be set and the gain value for those channels.

	* @return An error code. KErrNone on success.

	*                        KErrNotSupported if gain for unsupported channels is tried to be set.

	*                        KErrArgument if a value of less than 0 or larger than max gain is tried to be set as gain.

	*                        Other system wide error codes are also possible.

	*/

	virtual TInt SetGain(RArray<TAudioChannelGain>& aChannels)=0;

	/**

	* Returns channel specific gain settings.

	*

	* @param  aChannels On return contains current gain settings for each audio channel.

	* @return An error code. KErrNone on success.

	*                        KErrArgument if the array passed in as a parameter is not empty.

	*                        KErrOutOfMemory in case of memory exhaustion.

	*                        Other system wide error codes are also possible.

	*/

	virtual TInt GetGain(RArray<TAudioChannelGain>& aChannels) const= 0;

	/**

	* Registers an observer for receiving callbacks.

	*

	* @param aObserver a reference to the observer to register.

	* @return An error code. KErrNone on success, otherwise one of the system wide error codes.

	*/

	virtual TInt RegisterAudioGainControlObserver(MAudioGainControlObserver& aObserver)=0;

	/**

	* Unregisters an observer.

	*

	* @param aObserver a reference to observer to unregister.

	*/

	virtual void UnregisterAudioGainControlObserver(MAudioGainControlObserver& aObserver)=0;

	};

#endif // MAUDIOGAINCONTROL_H