// Copyright (c) 2001-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 DEVSOUNDPLUGIN_H

#define DEVSOUNDPLUGIN_H

_LIT8(KDevSoundPluginMatchString, "*"); // ECom insists on something

/**

Interface class used in the plugin implementation of DevSound.

The CMMFDevSound implementation loads a plugin based on this interface class. 

Once this has been constructed, calls to method functions of CMMFDevSound are passed

verbatim to this interface. For further description of required functionality, 

see CMMFDevSound.

@see CMMFDevSound

*/

class MMMFDevSoundPlugin

	{

public:

	/**	

	This must provide an implementation as defined by CMMFDevSound::~CMMFDevSound()

	@see CMMFDevSound::~CMMFDevSound()

	*/

	virtual ~MMMFDevSoundPlugin() {}

	/**

	This must provide an implementation as defined by 

	CMMFDevSound::InitializeL(MDevSoundObserver& aDevSoundObserver, TMMFState aMode)

	@param  aDevSoundObserver

	        A reference to DevSound Observer instance.

	@param  aMode

	        The mode for which this object will be used.

	@see CMMFDevSound::InitializeL(MDevSoundObserver& aDevSoundObserver, TMMFState aMode)

	*/

    virtual void InitializeL(MDevSoundObserver& aDevSoundObserver, TMMFState aMode)=0;

	/**

	This must provide an implementation as defined by 

	CMMFDevSound::InitializeL(MDevSoundObserver& aDevSoundObserver, TUid aHWDev, TMMFState aMode)

	@param  aDevSoundObserver

	        A reference to DevSound Observer instance.

	@param  aHWDev

	        The CMMFHwDevice implementation identifier.

	@param  aMode

	        The mode for which this object will be used.

	@see CMMFDevSound::InitializeL(MDevSoundObserver& aDevSoundObserver, TUid aHWDev, TMMFState aMode)

	*/

	virtual void InitializeL(MDevSoundObserver& aDevSoundObserver, TUid aHWDev, TMMFState aMode)=0;

	/**

	This must provide an implementation as defined by 

	CMMFDevSound::InitializeL(MDevSoundObserver& aDevSoundObserver, TFourCC aDesiredFourCC, TMMFState aMode)

	@param  aDevSoundObserver

	        A reference to DevSound Observer instance.

	@param  aDesiredFourCC

	        The CMMFHwDevice implementation FourCC code.

	@param  aMode

	        The mode for which this object will be used.

	@see CMMFDevSound::InitializeL(MDevSoundObserver& aDevSoundObserver, TFourCC aDesiredFourCC, TMMFState aMode)

	*/

	virtual void InitializeL(MDevSoundObserver& aDevSoundObserver, TFourCC aDesiredFourCC, TMMFState aMode)=0;

	/**

	This must provide an implementation as defined by CMMFDevSound::Capabilities()

	@return	The device settings.

	@see CMMFDevSound::Capabilities()

	*/

	virtual TMMFCapabilities Capabilities()=0;

	/**

	This must provide an implementation as defined by CMMFDevSound::Config()

	@return	The device settings.

	@see CMMFDevSound::Config()

	*/

	virtual TMMFCapabilities Config() const=0;

	/**

	This must provide an implementation as defined by CMMFDevSound::SetConfigL(const TMMFCapabilities& aCaps)

	@param  aCaps The attribute values to which CMMFDevSound object will be configured to.

	@see CMMFDevSound::SetConfigL(const TMMFCapabilities& aCaps)

	*/

	virtual void SetConfigL(const TMMFCapabilities& aCaps)=0;

	/**

	This must provide an implementation as defined by CMMFDevSound::MaxVolume()

	@return	The maximum volume. This value is platform dependent but is always greater than or equal

	to one.

	@see CMMFDevSound::MaxVolume()

	*/

	virtual TInt MaxVolume()=0;

	/**

	This must provide an implementation as defined by CMMFDevSound::Volume()

	@return The current volume level.

	@see CMMFDevSound::Volume()

	*/

	virtual TInt Volume()=0;

	/**

	This must provide an implementation as defined by CMMFDevSound::SetVolume()

	@param  aVolume

	        The volume setting. This can be any value from 0 to the value

	        returned by a call to CMMFDevSound::MaxVolume(). If the

	        volume is not within this range, the volume is automatically set to

	        minimum or maximum value based on the value that is being passed.

	        Setting a zero value mutes the sound. Setting the maximum value

	        results in the loudest possible sound.

	@see CMMFDevSound::SetVolume()

	*/

	virtual void SetVolume(TInt aVolume)=0;

	/**

	This must provide an implementation as defined by CMMFDevSound::MaxGain()

	@return The maximum gain. This value is platform dependent but is always greater than or equal

	to one.

	@see CMMFDevSound::MaxGain()

	*/

	virtual TInt MaxGain()=0;

	/**

	This must provide an implementation as defined by CMMFDevSound::Gain()

	@return The current gain level.

	@see CMMFDevSound::Gain()

	*/

	virtual TInt Gain()=0;

	/**

	This must provide an implementation as defined by CMMFDevSound::SetGain()

	@param  aGain

		    The gain setting. This can be any value from zero to the value

		    returned by a call to CMMFDevSound::MaxGain(). If the

		    volume is not within this range, the gain is automatically set to

		    minimum or maximum value based on the value that is being passed.

		    Setting a zero value mutes the sound. Setting the maximum value

		    results in the loudest possible sound.

	@see CMMFDevSound::SetGain()

	*/

	virtual void SetGain(TInt aGain)=0;

	/**

	This must provide an implementation as defined by 

	CMMFDevSound::GetPlayBalanceL(TInt& aLeftPercentage, TInt& aRightPercentage)

	@param  aLeftPercentage

	        On return contains the left speaker volume percentage.

	@param  aRightPercentage

	        On return contains the right speaker volume percentage.

	@see CMMFDevSound::GetPlayBalanceL(TInt& aLeftPercentage, TInt& aRightPercentage)

	*/

	virtual void GetPlayBalanceL(TInt& aLeftPercentage, TInt& aRightPercentage)=0;

	/**

	This must provide an implementation as defined by 

	CMMFDevSound::SetPlayBalanceL(TInt aLeftPercentage, TInt aRightPercentage)

	@param  aLeftPercentage

	        On return contains left speaker volume perecentage. This can be any

	        value from zero to 100. Setting a zero value mutes the sound on left

	        speaker.

	@param  aRightPercentage

	        On return contains right speaker volume perecentage. This can be any

	        value from zero to 100. Setting a zero value mutes the sound on

	        right speaker.

	@see CMMFDevSound::SetPlayBalanceL(TInt aLeftPercentage, TInt aRightPercentage)

	*/

	virtual void SetPlayBalanceL(TInt aLeftPercentage, TInt aRightPercentage)=0;

	/**

	This must provide an implementation as defined by 

	CMMFDevSound::GetRecordBalanceL(TInt& aLeftPercentage, TInt& aRightPercentage)

	@param  aLeftPercentage

	        On return contains the left microphone gain percentage.

	@param  aRightPercentage

	        On return contains the right microphone gain percentage.

	@see CMMFDevSound::GetRecordBalanceL(TInt& aLeftPercentage, TInt& aRightPercentage)

	*/

	virtual void GetRecordBalanceL(TInt& aLeftPercentage, TInt& aRightPercentage)=0;

	/**

	This must provide an implementation as defined by 

	CMMFDevSound::GetRecordBalanceL(TInt aLeftPercentage, TInt aRightPercentage)

	@param  aLeftPercentage

	        The left microphone gain precentage. This can be any value from zero to

	        100. Setting a zero value mutes the gain on left microphone.

	@param  aRightPercentage

	        The right microphone gain precentage. This can be any value from zero to

	        100. Setting a zero value mutes the gain on right microphone.

	@see CMMFDevSound::GetRecordBalanceL(TInt aLeftPercentage, TInt aRightPercentage)

	*/

	virtual void SetRecordBalanceL(TInt aLeftPercentage, TInt aRightPercentage)=0;

	/**

	This must provide an implementation as defined by CMMFDevSound::PlayInitL()

	@see CMMFDevSound::PlayInitL()

	*/

	virtual void PlayInitL()=0;

	/**

	This must provide an implementation as defined by CMMFDevSound::RecordInitL()

	@see CMMFDevSound::RecordInitL()

	*/

	virtual void RecordInitL()=0;

	/**

	This must provide an implementation as defined by CMMFDevSound::PlayData()

	@see CMMFDevSound::PlayData()

	*/

	virtual void PlayData()=0;

	/**

	This must provide an implementation as defined by CMMFDevSound::RecordData()

	@see CMMFDevSound::RecordData()

	*/

	virtual void RecordData()=0;

	/**

	This must provide an implementation as defined by CMMFDevSound::Stop()

	@see CMMFDevSound::Stop()

	*/

	virtual void Stop()=0;

	/**

	This must provide an implementation as defined by CMMFDevSound::Pause()

	@see CMMFDevSound::Pause()

	*/

	virtual void Pause()=0;

	/**

	This must provide an implementation as defined by CMMFDevSound::SamplesRecorded()

	@return The samples recorded.

	@see CMMFDevSound::SamplesRecorded()

	*/

	virtual TInt SamplesRecorded()=0;

	/**

	This must provide an implementation as defined by CMMFDevSound::SamplesPlayed()

	@return The samples played.

	@see CMMFDevSound::SamplesPlayed()

	*/

	virtual TInt SamplesPlayed()=0;

	/**

	This must provide an implementation as defined by 

	CMMFDevSound::PlayToneL(TInt aFrequency, const TTimeIntervalMicroSeconds& aDuration)

	@param  aFrequency

	        The frequency at which the tone will be played.

	@param  aDuration

	        The period over which the tone will be played. A zero value causes

	        the no tone to be played.

	@see CMMFDevSound::PlayToneL(TInt aFrequency, const TTimeIntervalMicroSeconds& aDuration)

	*/

	virtual void PlayToneL(TInt aFrequency, const TTimeIntervalMicroSeconds& aDuration)=0;

	/**

	This must provide an implementation as defined by 

	CMMFDevSound::PlayDualToneL(TInt aFrequencyOne, TInt aFrequencyTwo, const TTimeIntervalMicroSeconds& aDuration)

	@param  aFrequencyOne

	        The first frequency of dual tone.

	@param  aFrequencyTwo

	        The second frequency of dual tone

	@param  aDuration

	        The period over which the tone will be played. A zero value causes

	        the no tone to be played (Verify this with test app).

	@see CMMFDevSound::PlayDualToneL(TInt aFrequencyOne, TInt aFrequencyTwo, const TTimeIntervalMicroSeconds& aDuration)

	*/

	virtual void PlayDualToneL(TInt aFrequencyOne, TInt aFrequencyTwo, const TTimeIntervalMicroSeconds& aDuration)=0;

	/**

	This must provide an implementation as defined by CMMFDevSound::PlayDTMFStringL(const TDesC& aDTMFString)

	@param  aDTMFString The DTMF sequence in a descriptor.

	@see CMMFDevSound::PlayDTMFStringL(const TDesC& aDTMFString)

	*/

	virtual void PlayDTMFStringL(const TDesC& aDTMFString)=0;

	/**

	This must provide an implementation as defined by CMMFDevSound::PlayToneSequenceL(const TDesC8& aData)

	@param  aData The tone sequence in a descriptor.

	@see CMMFDevSound::PlayToneSequenceL(const TDesC8& aData)

	*/

	virtual void PlayToneSequenceL(const TDesC8& aData)=0;

	/**

	This must provide an implementation as defined by CMMFDevSound::PlayFixedSequenceL(TInt aSequenceNumber)

	@param  aSequenceNumber

	        The index identifying the specific pre-defined tone sequence. Index

	        values are relative to zero.

	        This can be any value from zero to the value returned by a call to

	        FixedSequenceCount() - 1.

	        The function raises a panic if the sequence number is not within this

	        range.

	@see CMMFDevSound::PlayFixedSequenceL(TInt aSequenceNumber)

	@see FixedSequenceCount()

	*/

	virtual void PlayFixedSequenceL(TInt aSequenceNumber)=0;

	/**

	This must provide an implementation as defined by 

	CMMFDevSound::SetToneRepeats(TInt aRepeatCount,

					const TTimeIntervalMicroSeconds& aRepeatTrailingSilence)

	@param  aRepeatCount

	        The number of times the tone, together with the trailing silence,

	        is to be repeated. If this is set to KMdaRepeatForever, then the

	        tone, together with the trailing silence, is repeated indefinitely

	        or until Stop() is called. If this is set to zero, then the tone is

	        not repeated.

	@param  aRepeatTrailingSilence

	        An interval of silence which will be played after each tone.

	        Supported only during tone playing.

	@see CMMFDevSound::SetToneRepeats(TInt aRepeatCount,

					const TTimeIntervalMicroSeconds& aRepeatTrailingSilence)

	*/

	virtual void SetToneRepeats(TInt aRepeatCount,

					const TTimeIntervalMicroSeconds& aRepeatTrailingSilence)=0;

	/**

	This must provide an implementation as defined by 

	CMMFDevSound::(TTimeIntervalMicroSeconds32& aToneOnLength,

									TTimeIntervalMicroSeconds32& aToneOffLength,

									TTimeIntervalMicroSeconds32& aPauseLength)

	@param  aToneOnLength

	        The period over which the tone will be played. If this is set to

	        zero, then the tone is not played.

	@param  aToneOffLength

	        The period over which the no tone will be played.

	@param  aPauseLength

	        The period over which the tone playing will be paused.

	@see CMMFDevSound::(TTimeIntervalMicroSeconds32& aToneOnLength,

									TTimeIntervalMicroSeconds32& aToneOffLength,

									TTimeIntervalMicroSeconds32& aPauseLength)

	*/

	virtual void SetDTMFLengths(TTimeIntervalMicroSeconds32& aToneOnLength,

									TTimeIntervalMicroSeconds32& aToneOffLength,

									TTimeIntervalMicroSeconds32& aPauseLength)=0;

	/**

	This must provide an implementation as defined by 

	CMMFDevSound::SetVolumeRamp(const TTimeIntervalMicroSeconds& aRampDuration)

	@param  aRampDuration

	        The period over which the volume is to rise. A zero value causes

	        the tone sample to be played at the normal level for the full

	        duration of the playback. A value, which is longer than the duration

	        of the tone sample means that the sample never reaches its normal

	        volume level.

	@see CMMFDevSound::SetVolumeRamp(const TTimeIntervalMicroSeconds& aRampDuration)

	*/

	virtual void SetVolumeRamp(const TTimeIntervalMicroSeconds& aRampDuration)=0;

	/**

	This must provide an implementation as defined by 

	CMMFDevSound::SetPrioritySettings(const TMMFPrioritySettings& aPrioritySettings)

	@param	aPrioritySettings 

			A class type representing the client's priority, priority preference and state.

	@see CMMFDevSound::SetPrioritySettings(const TMMFPrioritySettings& aPrioritySettings)

	*/

	virtual void SetPrioritySettings(const TMMFPrioritySettings& aPrioritySettings)=0;

	/**

	This must provide an implementation as defined by CMMFDevSound::CustomInterface(TUid aInterfaceId)

	@param  aInterfaceId

	        The interface UID, defined with the custom interface.

	@return A pointer to the interface implementation, or NULL if the device does not

	        implement the interface requested. The return value must be cast to the

	        correct type by the user.The user should be careful while caching the custom interface pointer,

	        as in some situations the lower level custom interface pointer may become NULL

	@see CMMFDevSound::CustomInterface(TUid aInterfaceId)

	*/

	virtual TAny* CustomInterface(TUid aInterfaceId)=0;

	/**

	This must provide an implementation as defined by CMMFDevSound::FixedSequenceCount()

	@return The fixed sequence count. This value is implementation dependent but is always greater 

	        than or equal to zero.

	@see CMMFDevSound::FixedSequenceCount()

	*/

	virtual TInt FixedSequenceCount()=0;

	/**

	This must provide an implementation as defined by CMMFDevSound::FixedSequenceName(TInt aSequenceNumber)

	@param  aSequenceNumber

	        The index identifying the specific pre-defined tone sequence. Index values are relative 

	        to zero. This can be any value from zero to the value returned by a call to

	        FixedSequenceCount() - 1.

	        The function raises a panic if sequence number is not within this

	        range.

	@return A reference to a Descriptor containing the fixed sequence name indexed by

	        aSequenceNumber.

	@see CMMFDevSound::FixedSequenceName(TInt aSequenceNumber)

	@see FixedSequenceCount()

	*/

	virtual const TDesC& FixedSequenceName(TInt aSequenceNumber)=0;

	/**

	This must provide an implementation as defined by 

	CMMFDevSound::GetSupportedInputDataTypesL(RArray<TFourCC>& aSupportedDataTypes,

													const TMMFPrioritySettings& aPrioritySettings) const

	@param  aSupportedDataTypes

	        The array of supported data types that will be filled in by this function.

	        The supported data types of the DevSound are in the form of an array

	        of TFourCC codes. Any existing entries in the array will be overwritten on 

	        calling this function. If no supported data types are found given the priority 

	        settings, then the aSupportedDatatypes array will have zero entries.

	@param  aPrioritySettings

	        The priority settings used to determine the supported datatypes.  Note this

	        does not set the priority settings. For input datatypes the iState member

	        of the priority settings would be expected to be either

	        EMMFStatePlaying or EMMFStatePlayingRecording. The priority settings may

	        effect the supported datatypes depending on the audio routing.

	@see CMMFDevSound::GetSupportedInputDataTypesL(RArray<TFourCC>& aSupportedDataTypes,

													const TMMFPrioritySettings& aPrioritySettings) const

	*/

	virtual void GetSupportedInputDataTypesL(RArray<TFourCC>& aSupportedDataTypes, const TMMFPrioritySettings& aPrioritySettings) const=0;

	/**

	This must provide an implementation as defined by 

	CMMFDevSound::GetSupportedOutputDataTypesL(RArray<TFourCC>& aSupportedDataTypes, const TMMFPrioritySettings& aPrioritySettings) const

	@param  aSupportedDataTypes

	        The array of supported data types that will be filled in by this function.

	        The supported datatypes of the DevSound are in the form of an array

	        of TFourCC codes.

	        Any existing entries in the array will be overwritten on calling this function.

	        If no supported datatypes are found given the priority settings, then

	        the aSupportedDatatypes array will have zero entries.

	@param  aPrioritySettings

	        The priority settings used to determine the supported data types.  Note this

	        does not set the priority settings. For output data types the iState member

	        of the priority settings would expected to be either

	        EMMFStateRecording or EMMFStatePlayingRecording. The priority settings may

	        effect the supported datatypes depending on the audio routing.

	@see CMMFDevSound::GetSupportedOutputDataTypesL(RArray<TFourCC>& aSupportedDataTypes, const TMMFPrioritySettings& aPrioritySettings) const

	*/

	virtual void GetSupportedOutputDataTypesL(RArray<TFourCC>& aSupportedDataTypes, const TMMFPrioritySettings& aPrioritySettings) const=0;

	};

#endif // DEVSOUNDPLUGIN_H