diff -r 000000000000 -r 40261b775718 devsound/a3facf/inc/maudiogaincontrol.h --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/devsound/a3facf/inc/maudiogaincontrol.h Tue Feb 02 01:56:55 2010 +0200 @@ -0,0 +1,150 @@ +/* +* 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 +#include +#include +#include + +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& 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& 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& 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