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