--- /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 <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