// MmfGlblAudioEffect.h

 // Copyright (c) 2005-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:

 //

 #ifndef MMFGLBLAUDIOEFFECT_H

 #define MMFGLBLAUDIOEFFECT_H

 #include <e32std.h>

 #include <e32base.h>

 #include <bamdesca.h>

 #include <mmf/common/mmfbase.hrh>

 /**

 @publishedPartner

 @released

 @file

 */

 //forward decs

 class MMmfGlobalAudioImpl;

 class CMmfGlobalAudioEffect;

 class MMmfGlobalAudioPresetList;

 /**

 Notify changes as requested

 */

 class MMmfGlobalAudioEffectObserver

 	{

 public:

     /**

     Callback that event is occuring, as requested.

     This pairs with CMmfGlobalAudioEffect::RequestNotificationL()

     @param aEffect 

            The effect object from where the notification is being signaled

     @param aEventUid

            The uid passed to CMmfGlobalAudioEffect::RequestNotificationL()

     @param aParam

            Parameter data, exact use will depend on aEventUid

     @see CMmfGlobalAudioEffect::RequestNotificationL()

     */

 	virtual void GAEEventNotificationL(CMmfGlobalAudioEffect* aEffect, TUid aEventUid, const TDesC8& aParam)=0;

 	};

 /**

 EnableChanged event Uid

 @see CMmfGlobalAudioEffect::RequestNotificationL()

 */

 const TUid KUidMmfGlblAudioEnableChanged = {KUidMmfGlblAudioEnableChangedDefine};

 /**

 ActiveChanged event Uid

 @see CMmfGlobalAudioEffect::RequestNotificationL()

 */

 const TUid KUidMmfGlblAudioActiveChanged = {KUidMmfGlblAudioActiveChangedDefine};   

 /**

 PresetsChanged event Uid

 @see CMmfGlobalAudioEffect::RequestNotificationL()

 */

 const TUid KUidMmfGlblAudioPresetsChanged = {KUidMmfGlblAudioPresetsChangedDefine};

 /**

 The value associated with the callback has been changed

 @see CMmfGlobalAudioEffect::RequestNotificationL()

 */

 const TUid KUidMmfGlblAudioValueChanged = {KUidMmfGlblAudioValueChangedDefine};

 /**

 Parent class for global audio effects

 All global effect class derive from this class. It should be seen as an abstract class providing

 common facilities, that they all share. Users of these classes should be aware that there could

 be multiple instances, at any one go - e.g. in separate processes. All instances should use

 event notification (see RequestNotificationL()) to observe changes in values, in case another

 instance has changed things.

 If there is more than one output device on a phone, then the behaviour is system dependent,

 but typical behaviour would be for the settings etc only to apply to the current device - 

 switching output device would lead to a direct change in the settings reported.

 */

 class CMmfGlobalAudioEffect : public CBase

 	{

 public:

 	/**

 	Destructor. 

 	*/

 	IMPORT_C ~CMmfGlobalAudioEffect();

 	/**

 	Flags denoting capability of specific global effect.

 	These flags allow the client app to equire about the capabilities of the given effect.

 	It should be noted that these refer to the specific implementation, and not 

 	necessarily the effect class

 	*/

 	enum TCapabilityFlags

 		{

 		ECapabilitySupportsInvidividualValues	=0x0001, 	//*< Supports ExtractValuesL() and SetByValuesL()

 		ECapabilitySupportsSettingByUid			=0x0002, 	//*< Supports current setting to be requested by Uid

 		ECapabilitySupportsSetSettingByUid		=0x0004,	//*< Supports current value to be changed by Uid

 		ECapabilitySupportsSettingByDes			=0x0008,	//*< Supports current setting to be required by Descriptor

 		ECapabilitySupportsSetSettingByDes		=0x0010,	//*< Supports current value to be changed by Descriptor

 		ECapabilitySupportsActiveChangedCallback=0x0020,	//*< Supports KUidMmfGlblAudioActiveChanged callbacks

 		ECapabilitySupportsEnableChangedCallback=0x0040,	//*< Supports KUidMmfGlblAudioEnableChanged callbacks

 		ECapabilitySupportsPresetChangedCallback=0x0080,	//*< Supports KUidMmfGlblAudioPresetsChanged callbacks

 		};

 	/**

 	Indication of how to interpret volume settings.

 	*/

 	enum TVolumeValue

 		{

 		EVolValueAbsolute, 	//*< Interpret volume and similar values as some form of absolute scale

 		EVolValuedB			//*< Interpret volume and similar values as dB

 		};

 	/**

 	Request capabilities of this object.

 	Return the capabilities of the particular GlobalAudioEffect. If aCurrentOnly is false, then

 	it will return all the possible features of the implementation, whereas if it is true only

 	the features available at that moment are indicated. For example, an implementation may

 	support returning the value by UID, but if it was set by UID. In such a circumstance, the

 	bit will always be true if aCurrentOnly is false, but if aCurrentOnly is true and the

 	value had been (say) set by descriptor, then that bit will be false.

 	@param aCurrentOnly

 	       If true, capabilities are for current situation only - see text

 	@return Capability settings, as given in TCapabilityFlags

 	*/	

 	IMPORT_C TUint Capability(TBool aCurrentOnly);

 	/**

 	Request to be told about particular events occuring

 	This is a generic facility for providing callbacks as particular events occur. All callbacks

 	are sent to the Observer that was passed on object creation, invoking GAEEventNotificationL(). 

 	The following Uids are defined:

 	KUidMmfGlblAudioEnableChanged - Indicates the value of IsEnabled() has changed.

 	KUidMmfGlblAudioActiveChanged - Indicates the value of IsActive() has changed.

 	KUidMmfGlblAudioPresetsChanged - Indicates the list of known presets etc has been modified.

 	KUidMmfGlblAudioValueChanged - Indicates the settings have been changed

 	With all these settings, the value of aParam returned to GAEEventNotificationL() will be empty.

 	@param aEventUid

 	       Uid specifying event for which notification is requested

 	@leave KErrNotSupported

 	       If Observer passed during construction was NULL.

 	       The Uid is not recognised.

 	       The feature is simply not supported in this implementation.

 	@see MMmfGlobalAudioEffectObserver::GAEEventNotificationL()

 	*/

 	IMPORT_C void RequestNotificationL(TUid aEventUid);

 	/**

 	The particular effect is enabled

 	@return True if SetEnabledL(ETrue), or similar, has been called on this effect

 	@see SetEnabledL()

 	*/

 	IMPORT_C TBool IsEnabled() const;

 	/**

 	The particular effect is active

 	Active is defined as being that the effect is in use - that is audio data is being played

 	through it

 	@return True if the effect is in use

 	*/

 	IMPORT_C TBool IsActive() const;

 	/**

 	Enable (or disable) this effect

 	If not enabled, the Effect will not change the data being passed through. However, the

 	values associated with the effect. Where audio data is being played, the effect will

 	take place immediately. 

 	@param aValue

 	       If true, enables this specific effect. If false, disables it. 

 	*/

 	IMPORT_C void SetEnabledL(TBool aValue);

 	/**

 	Obtain uid-based current settings

 	If the value was set using SetSettingsByUidL() then this returns that setting. Note: can use 

 	Capability(ETrue) to avoid unnecessarily leave.

 	@return The Uid used by SetSettingsByUidL()

 	@leave KErrNotSupported

 	       The settings cannot be expressed as a Uid (usually means SetSettingsByUidL() was not the last

 	       thing to change them).

 	*/

 	IMPORT_C TUid SettingsByUidL() const;

 	/**

 	Change settings by passing Uid

 	Change the settings using a uid, that represents a preset. The uid could be known, but

 	should preferably be obtained by using RequestPresets()

 	@param aPresetUid

 	       Uid representing the preset in question

 	@leave KErrNotSupported

 	       This implementation does not support presets for this effect

 	@leave KErrUnknown

 	       The value of aUid does not correspond to a known preset

 	@see RequestPresets()

 	*/

 	IMPORT_C void SetSettingsByUidL(TUid aPresetUid);

 	/**

 	Obtain current settings by descriptor

 	Return an HBufC8* representing the current settings. The format of this descriptor

 	is not specified, but in any given implementation it must be usable by SetSettingsByDesL().

 	Ownership of the descriptor is passed back to the calling code.

 	@return HBufC8 containing current settings

 	@leave KErrNotSupported

 	       This implementation does not support expressing settings in descriptor form

 	@see SetSettingsByDesL()

 	*/

 	IMPORT_C HBufC8* SettingsByDesL() const;

 	/**

 	Change settings by descriptor

 	Update the current settings from values stored in a descriptor. The value in the 

 	descriptor will typically have been created using SettingsByDesL().

 	@param aParam

 	       Descriptor value to use

 	@leave KErrNotSupported

 	       This implementation does not support expressing settings in descriptor form

 	@leave KErrCorrupt

 	       Value in descriptor does not correspond to known format	  

 	*/

 	IMPORT_C void SetSettingsByDesL(const TDesC8& aParam);

 	/**

 	Return info about known presets by Uid

 	This is used in connection with SetSettingsByUidL(). It allows the user to select a preset by

 	name but this to be fed back as a Uid. It should also allow a Uid to be translated back to

 	a name, if required. Ownership of the list itself remains within the effect implementation.

 	The list may be changed on each call to KnownPresetsL() - users should be careful about 

 	caching the returned pointer.

 	@return List of known preset names and uids

 	@see SetSettingsByUidL()

 	@leave KErrNotSupported

 	       This feature may not be supported in some circumstances

 	*/

 	IMPORT_C MMmfGlobalAudioPresetList* KnownPresetsL();

 	/**

 	Extract the settings into a struct

 	This extracts the current settings, and other data such as min/max values supported. 

 	This is intended to support direct selecting of values via graphical controls.

 	Unlike SettingsByDesL(), the parameter is expected to be a package buffer wrapping a

 	known class/struct, which will be defined by the particular derivation of this class.

 	@param aPackageBuf

 	       This should be a package buffer wrapping the appropriate class/struct, and will be 

 	       specific to a particular CMmfGlobalAudioEffect derivitive.

 	@leave KErrNotSupported

 	       This will only be supported by some child classes, and even then will not

 	       be supported by all implementations.

 	*/

 	IMPORT_C void ExtractValuesL(TDes8& aPackageBuf);

 	/**

 	Sets current settings from appropriate struct.

 	This takes the same struct as used for ExtractValuesL() and changes the current settings.

 	Typically it will be used at the end of a dialog to update the data.

 	@param aPackageBuf

 	       This should be a package buffer wrapping the appropriate class/struct, and will be 

 	       specific to a particular CMmfGlobalAudioEffect derivitive.

 	@leave KErrNotSupported

 	       This will only be supported by some child classes, and even then will not

 	       be supported by all implementations.

 	@leave KErrArgument

 		   Passed package buffer is not the expected size, or individual values are out of range

 	*/

 	IMPORT_C void SetByValuesL(const TDesC8& aPackageBuf);

 protected:

 	IMPORT_C CMmfGlobalAudioEffect();

 	/**

 	Should be called in the ConstructL() of any derived type

 	@param aImplementationUid

 	       Fixed for a given derived class, it is used to find the correct plugin or similar

 	       that implements that class.

 	@param aObserver

 	       Observer class. Could be NULL, in which case RequestNotificationL() would not be supported

 	@leave KErrNotSupported

 	       Cannot find implementation for given derived class

 	*/

 	IMPORT_C void BaseConstructL(TUid aImplementationUid, MMmfGlobalAudioEffectObserver* aObserver);

 	/**

 	Request extension feature.

 	This is intended to provide additional features, should a particular global effect

 	need it. In typical use, the global effect will make a call to this interface on

 	construction. Repeatedly calling this interface will have no additional effect -

 	if the interface has already been setup internally, then no further activity will

 	take place.

 	@param aInterfaceUid

 	       Used to indicate which interface is required. 

 	@return Standard error code. KErrNotSupported is used to indicate that the particular

 	        plugin is used.

 	*/

 	IMPORT_C TInt CreateCustomInterface(TUid aInterfaceUid);

 	/**

 	Return previously created extension.

 	This returns a custom interface, used to provide additional features for a certain

 	global effect. This should only be used if CreateCustomInterface() has already

 	been called for the same UID value. This means that any construction for that interface

 	has already been called, and thus this call cannot fail. Typically the returned class 

 	will be another Mixin.No transfer of ownership is implied. 

 	@param aInterfaceUid

 	       Used to indicate which interface is required. 

 	@return The requested interface, or NULL if not known.

 	@see CreateCustomInterface()

 	*/

 	IMPORT_C TAny* CustomInterface(TUid aInterfaceUid);

 private:

 	MMmfGlobalAudioImpl* iBaseImplementation; //*< Implementation Object

 	};

 /**

 List of preset names against their Uid

 Array of preset name and uid pairs. Returned by CMmfGlobalAudioEffect::KnownPresetsL()

 @see CMmfGlobalAudioEffect::KnownPresetsL()

 */

 class MMmfGlobalAudioPresetList : public MDesCArray

 	{

 public:

 	/**

 	Return Uid corresponding to the name of the same index - the name being returned by

 	McaPoint()

 	@param aIndex

 	       Select element from list

 	@return Uid of that element

 	*/

 	virtual TUid GAPUidPoint(TInt aIndex) const=0;

 	};

 #endif // MMFGLBLAUDIOEFFECT_H