// MmfGlblAudioEffectPlugin.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 MMFGLBLAUDIOEFFECTPLUGIN_H
#define MMFGLBLAUDIOEFFECTPLUGIN_H

#include <mmf/common/mmfglblaudioeffect.h>

/**
@publishedPartner
@released
@file
*/

/**
Implementation of CMmfGlobalAudioEffect.
This is the base interface for plugins that provide for global effects. It is intended
to be exclusively called from CMmfGlobalAudioEffect itself.
 */
 
class MMmfGlobalAudioImpl
	{
	friend class CMmfGlobalAudioEffect; 
	
public:
	/**
	Release object.
	Equivalent of destructor - called to request data to be deleted.
	*/
	virtual void Release()=0;

protected:
	/*
	Provide implementation of CMmfGlobalAudioEffect::Capability()
	@param aCurrentOnly
	       If true, capabilities are for current situation only - see text
	@return Capability settings, as given in TCapabilityFlags
	@see CMmfGlobalAudioEffect::Capability()
	*/	
	virtual TUint Capability(TBool aCurrentOnly)=0;
	
	/**
	Provide implementation of CMmfGlobalAudioEffect::RequestNotificationL()
	@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 CMmfGlobalAudioEffect::RequestNotificationL()
	*/
	virtual void RequestNotificationL(TUid aEventUid)=0;
	
	/**
	Provide implementation of CMmfGlobalAudioEffect::IsEnabled()
	@return True if SetEnabledL(ETrue), or similar, has been called on this effect
	@see CMmfGlobalAudioEffect::IsEnabled()
	*/
	virtual TBool IsEnabled() const=0;
	
	/**
	Provide implementation of CMmfGlobalAudioEffect::IsActive()
	@return True if the effect is in use
	@see CMmfGlobalAudioEffect::IsActive()
	*/
	virtual TBool IsActive() const=0;
	
	/**
	Provide implementation of CMmfGlobalAudioEffect::SetEnabledL()
	@param aValue
	       If true, enables this specific effect. If false, disables it. 
	@see CMmfGlobalAudioEffect::SetEnabledL()
	*/
	virtual void SetEnabledL(TBool aValue)=0;
	
	/**
	Provide implementation of CMmfGlobalAudioEffect::SettingsByUidL()
	@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).
	@see CMmfGlobalAudioEffect::SettingsByUidL()
	*/
	virtual TUid SettingsByUidL() const=0;
	
	/**
	Provide implementation of CMmfGlobalAudioEffect::SetSettingsByUidL()
	@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 CMmfGlobalAudioEffect::SetSettingsByUidL()
	*/
	virtual void SetSettingsByUidL(TUid aPresetUid)=0;
	
	/**
	Provide implementation of CMmfGlobalAudioEffect::SettingsByDesL()
	@return HBufC8 containing current settings
	@leave KErrNotSupported
	       This implementation does not support expressing settings in descriptor form
	@see CMmfGlobalAudioEffect::SettingsByDesL()
	*/
	virtual HBufC8* SettingsByDesL() const=0;
	
	/**
	Provide implementation of CMmfGlobalAudioEffect::SetSettingsByDesL()
	@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
	@see CMmfGlobalAudioEffect::SetSettingsByDesL()	  
	*/
	virtual void SetSettingsByDesL(const TDesC8& aParam)=0;
	
	/**
	Provide implementation of CMmfGlobalAudioEffect::KnownPresetsL()
	@see CMmfGlobalAudioEffect::KnownPresetsL()
	@leave KErrNotSupported
	       This feature may not be supported in some circumstances
	*/
	virtual MMmfGlobalAudioPresetList* KnownPresetsL()=0;
	
	/**
	Provide implementation of CMmfGlobalAudioEffect::ExtractValuesL()
	Extract the settings into a struct
	Note that the implementation should check the size of the supplied package buffer, to check
	it is as expected.
	@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.
	@see CMmfGlobalAudioEffect::ExtractValuesL()
	*/
	virtual void ExtractValuesL(TDes8& aPackageBuf)=0;
	
	/**
	Provide implementation of CMmfGlobalAudioEffect::SetByValuesL().
	Note that the implementation should check the size of the supplied package buffer, to check
	it is as expected.
	@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
	@see CMmfGlobalAudioEffect::SetByValuesL()
	*/
	virtual void SetByValuesL(const TDesC8& aPackageBuf)=0;
	
	/**
	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.
	*/
	virtual TInt CreateCustomInterface(TUid aInterfaceUid)=0;
	
	
	/**
	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()
	*/
	virtual TAny* CustomInterface(TUid aInterfaceUid)=0;
	
	
	/**
	Pass destructor key.
	Called on construction so plugin takes responsibility to call REComSession::DestroyedImplementation()
	@param aDestructorKey
	       The Uid returned by REComSession::CreateImplementationL() or similar
	*/
	virtual void PassDestructorKey(TUid aDestructorKey)=0;
	
	/**
	Complete construction.
	Pass additional values from the construction phase, used subsequently by the plugin.
	@param aParent
	       The CMmfGlobalAudioEffect that created this object
	@param aObserver
	       Observer as passed to CMmfGlobalAudioEffect::BaseConstructL()
	@see CMmfGlobalAudioEffect::BaseConstructL()
	*/
	virtual void CompleteConstructL(CMmfGlobalAudioEffect* aParent, MMmfGlobalAudioEffectObserver* aObserver)=0;
	
private:
	static MMmfGlobalAudioImpl* NewL(TUid aImplementationUid, 
									 CMmfGlobalAudioEffect* aParent,
	                                 MMmfGlobalAudioEffectObserver* aObserver);
	
	};


#endif // MMFGLBLAUDIOEFFECTPLUGIN_