sl@0: /*
sl@0: * Copyright (c) 2006-2009 Nokia Corporation and/or its subsidiary(-ies).
sl@0: * All rights reserved.
sl@0: * This component and the accompanying materials are made available
sl@0: * under the terms of "Eclipse Public License v1.0"
sl@0: * which accompanies this distribution, and is available
sl@0: * at the URL "http://www.eclipse.org/legal/epl-v10.html".
sl@0: *
sl@0: * Initial Contributors:
sl@0: * Nokia Corporation - initial contribution.
sl@0: *
sl@0: * Contributors:
sl@0: *
sl@0: * Description:
sl@0: *
sl@0: */
sl@0: 
sl@0: 
sl@0: 
sl@0: #ifndef MMFDEVSOUNDADAPTATION_H
sl@0: #define MMFDEVSOUNDADAPTATION_H
sl@0: 
sl@0: //  INCLUDES
sl@0: #include <mmf/server/sounddevice.h>
sl@0: #include <a3f/a3f_trace_utils.h>
sl@0: 
sl@0: // CLASS FORWARD
sl@0: class MGlobalProperties;
sl@0: 
sl@0: const TInt KCallbackNone 				= 0;
sl@0: const TInt KCallbackProcessingFinished	= 1;
sl@0: const TInt KCallbackProcessingUnitError	= 2;
sl@0: const TInt KCallbackRecordPauseComplete	= 3;
sl@0: const TInt KCallbackAutoPauseResume 	= 4; 
sl@0: const TInt KCallbackFlushComplete		= 5;
sl@0: 
sl@0: // CLASS DECLARATION
sl@0: 
sl@0: /**
sl@0: @publishedAll
sl@0: @released
sl@0: 
sl@0: An interface to a set of DevSound adaptation observer callback functions.
sl@0: 
sl@0: This serves as the method of communication between the client and the
sl@0: DevSound.
sl@0: 
sl@0: The class is a mixin and is intended to be inherited by the client class
sl@0: that is interested in observing the DevSound operation. The functions
sl@0: encapsulated by this class are called when specific events occur in the
sl@0: process of initializing and playing/recording an audio sample or playing
sl@0: tones.
sl@0: */
sl@0: class MDevSoundAdaptationObserver
sl@0: 	{
sl@0: 	public:
sl@0: 	/**
sl@0: 	Handles initialization completion event.
sl@0: 
sl@0: 	A derived class must provide an implementation to handle the initialization
sl@0: 	request.
sl@0: 
sl@0: 	CMMFDevSound object calls this function when its InitializeL() function
sl@0: 	completes.
sl@0: 
sl@0: 	@param  aError
sl@0: 			Error code. KErrNone if successful. Other values are possible
sl@0: 			indicating a problem initializing CMMFDevSound object.
sl@0: 	*/
sl@0: 	virtual void InitializeComplete(TInt aError)=0;
sl@0: 
sl@0: 	/**
sl@0: 	Handles tone play completion event.
sl@0: 
sl@0: 	A derived class must provide an implementation to handle the tone play
sl@0: 	completion request.
sl@0: 
sl@0: 	CMMFDevSound object calls this function when an attempt to play tone has
sl@0: 	completed, successfully or otherwise.
sl@0: 
sl@0: 	The following are the play tone functions; PlayToneL(), PlayDMTFStringL(),
sl@0: 	PlayToneSequenceL(), and PlayFixedSequenceL().
sl@0: 
sl@0: 	@param  aError
sl@0: 			Error code. The status of tone playback. KErrUnderflow playing of
sl@0: 			the tone is complete. KErrAccessDenied the sound device is in use by
sl@0: 			another higher priority client. KErrCancel playing of the audio
sl@0: 			sample is stopped by DevSound client another higher priority client.
sl@0: 	*/
sl@0: 	virtual void ToneFinished(TInt aError)=0;
sl@0: 
sl@0: 	/**
sl@0: 	Handles CMMFDevSound object's data request event.
sl@0: 
sl@0: 	A derived class must provide an implementation to supply CMMFDevSound
sl@0: 	object the data that it needs to play.
sl@0: 
sl@0: 	CMMFDevSound object calls this function when and where it needs data for
sl@0: 	playing. The observer should notify CMMFDevSound object as
sl@0: 	quickly as possible after the data is read into buffer, aBuffer by calling
sl@0: 	PlayData(), otherwise the implementation might callback function PlayError()
sl@0: 	on derived class object with error code KErrUnderflow.
sl@0: 	This does not apply to the very first call to PlayData(), however.
sl@0: 	It is possible for a user of DevSound to hold the first buffer sent in
sl@0: 	BufferToBeFilled() until ready to play.
sl@0: 	The use case for this is if a low latency audio response
sl@0: 	is required, as at this point all the resources used to play audio are open.
sl@0: 	If used in this way then it is important to be aware that when when the
sl@0: 	resources for audio are ready at the BufferToBeFilled() callback, a Devsound
sl@0: 	on a real device will be running at increased power consumption as the audio
sl@0: 	hw and any required DSPs will be powered up etc.
sl@0: 
sl@0: 	@param  aBuffer
sl@0: 			Buffer into which data should be read. The amount of data that is
sl@0: 			needed is specified in CMMFBuffer::RequestSize().
sl@0: 	*/
sl@0: 	virtual void BufferToBeFilled(CMMFBuffer* aBuffer)=0;
sl@0: 
sl@0: 	/**
sl@0: 	Handles play completion or cancel event.
sl@0: 
sl@0: 	A derived class must provide an implementation to handle the play
sl@0: 	completion or cancel request.
sl@0: 
sl@0: 	CMMFDevSound object calls this function when an attempt to play audio sample
sl@0: 	has completed, successfully or otherwise.
sl@0: 
sl@0: 	@param  aError
sl@0: 			Error code. The status of playback. KErrUnderflow playing of the
sl@0: 			audio sample is complete. KErrAccessDenied the sound device is in
sl@0: 			use by another higher priority client.
sl@0: 	*/
sl@0: 	virtual void PlayError(TInt aError)=0;
sl@0: 
sl@0: 	/**
sl@0: 	Handles CMMFDevSound object's data request event.
sl@0: 
sl@0: 	A derived class must provide an implementation to process the data
sl@0: 	supplied by CMMFDevSound object while recording.
sl@0: 
sl@0: 	CMMFDevSound object calls this function when the buffer, aBuffer gets filled
sl@0: 	while recording. The observer should notify CMMFDevSound
sl@0: 	object as quickly as possible after data in the buffer is processed by
sl@0: 	calling RecordData(), otherwise the implementation might callback
sl@0: 	the function RecordError() on derived class object with error code KErrOverflow.
sl@0: 
sl@0: 	@param  aBuffer
sl@0: 			Buffer containing processed (recorded) data. The amount
sl@0: 			of data that is available is specified in CMMFBuffer::RequestSize().
sl@0: 	*/
sl@0: 	virtual void BufferToBeEmptied(CMMFBuffer* aBuffer)=0;
sl@0: 
sl@0: 	/**
sl@0: 	Handles record completion or cancel event.
sl@0: 
sl@0: 	A derived class must provide an implementation to handle the record
sl@0: 	completion or cancel request.
sl@0: 
sl@0: 	CMMFDevSound object calls this function when an attempt to record audio sample
sl@0: 	has completed, successfully or otherwise.
sl@0: 
sl@0: 	@param  aError
sl@0: 			Error code. The status of recording. KErrOverflow audio devices
sl@0: 			runs out of internal buffer. KErrAccessDenied the sound device is
sl@0: 			in use by another higher priority client.
sl@0: 	*/
sl@0: 	virtual void RecordError(TInt aError)=0;
sl@0: 
sl@0: 	/**
sl@0: 	Handles device event.
sl@0: 
sl@0: 	A derived class must provide an implementtion to handle the messages from
sl@0: 	audio hardware device.
sl@0: 
sl@0: 	CMMFDevSound object calls this function when a message is received from the
sl@0: 	audio hardware device.
sl@0: 
sl@0: 	@param  aMessageType
sl@0: 			Defines the type of message. Used to determine how to
sl@0: 			interpret the contents of aMsg.
sl@0: 	@param  aMsg
sl@0: 			Message that is packed in the Descriptor format.
sl@0: 	*/
sl@0: 	virtual void DeviceMessage(TUid aMessageType, const TDesC8& aMsg)=0;
sl@0: 
sl@0: 	/**
sl@0: 	A derived class must provide an implementation to handle the low layer operation completion
sl@0: 	@param	aError	The status of operation in progress
sl@0: 	@param	aCanStartNewOperation	If EFalse indicates that the operation has more than a cycle
sl@0: 	*/
sl@0: 	virtual void AsynchronousOperationComplete(TInt aError, TBool aCanStartNewOperation) = 0;
sl@0: 
sl@0: 
sl@0: 	/**
sl@0: 	Underlying interface has been (or is about to be) deleted.
sl@0: 	Implementations will generally cancel outstanding messages
sl@0: 
sl@0: 	@param	aInterfaceId	Uid of the Interface which has been deleted
sl@0: 	*/
sl@0: 	virtual void InterfaceDeleted(TUid aInterfaceId) = 0;
sl@0: 
sl@0: 	/*
sl@0: 	Underlying physical adaptation has sent a callback that will result either on a commit
sl@0: 	and need to scheduled or in the case of RecordPauseComplete, completes the message.
sl@0: 
sl@0: 	@param aType the callback type
sl@0: 	@param aError KErrNone if successful, else corresponding error
sl@0: 		code
sl@0: 	*/
sl@0: 	virtual void CallbackFromAdaptorReceived(TInt aType, TInt aError) = 0;
sl@0: 	
sl@0: 	/*
sl@0: 	Underlying physical adaptation has sent a callback indicating that a preemption process 
sl@0:  	has started, any incomming commands will be queued during the preemption.  
sl@0: 	*/
sl@0: 	virtual void PreemptionStartedCallbackReceived() = 0;
sl@0: 
sl@0: 	/*
sl@0: 	Underlying physical adaptation has sent a callback indicating that a preemption process
sl@0: 	has finished. Queued commands during preemption can now be processed. 
sl@0: 
sl@0: 	@param	aCanStartNewOperation	If EFalse indicates that the operation has more than a cycle
sl@0: 	*/
sl@0: 	virtual void PreemptionFinishedCallbackReceived(TBool aCanStartNewOperation) = 0;
sl@0: 
sl@0: 	/*
sl@0: 	 * The adaptor has control of the context.
sl@0: 	 * @return returns True if the adaptor is the entity responsible for calling Commit()
sl@0: 	 */
sl@0: 	virtual TBool AdaptorControlsContext() const = 0;
sl@0: 
sl@0: 	/*
sl@0: 	 * Callback indicating that a clash with pre-emption has occurred during the commit cycle
sl@0: 	 * and to push the current request that was being processed onto front of queue.
sl@0: 	 */
sl@0: 
sl@0: 	virtual void PreemptionClash() = 0;
sl@0: 
sl@0: 	/*
sl@0: 	 * Callback indicating the clash with pre-emption during the commit cycle was with state change,
sl@0: 	 * so the current request that was previously pushed onto the front of queue should be removed
sl@0: 	 * without processing.
sl@0: 	 */
sl@0: 
sl@0: 	virtual void PreemptionClashWithStateChange() = 0;
sl@0: 
sl@0: 	/*
sl@0: 	 * Callback to indicate an error has been noticed. This is to be cached until subsequent
sl@0: 	 * AsynchronousOperationComplete(), and handled then if needs.
sl@0: 	 */
sl@0: 	virtual void NotifyError(TInt aError) = 0;
sl@0: 
sl@0: 	};
sl@0: 
sl@0: // CLASS DECLARATION
sl@0: 
sl@0: /**
sl@0: @publishedAll
sl@0: @released
sl@0: * This class implements DevSound behavior in a hardware independent way.
sl@0: *
sl@0: *  @lib MmfDevSoundAdaptation.lib
sl@0: *  @since
sl@0: */
sl@0: class CMMFDevSoundAdaptation : public CBase
sl@0: {
sl@0: 
sl@0: public:  // Constructors and destructor
sl@0: 
sl@0: 	/**
sl@0: 	* Constructs, and returns a pointer to, a new CMMFDevSoundAdaptation
sl@0: 	* object.
sl@0: 	* Leaves on failure..
sl@0: 	* @param MDevSoundAdaptationObserver& aDevSoundObserver A reference to DevSound
sl@0: 	*        Observer instance.
sl@0: 	* @param MGlobalPrpoerties a reference to Audio Server global properties
sl@0: 	* @return CMMFDevSoundAdaptation* A pointer to newly created object.
sl@0: 	*/
sl@0: 	IMPORT_C static CMMFDevSoundAdaptation* NewL(MDevSoundAdaptationObserver& aDevSoundObserver,
sl@0: 														MGlobalProperties& aGlobalProperties);
sl@0: 
sl@0: 	/**
sl@0: 	* Destructor.
sl@0: 	*/
sl@0: 	IMPORT_C virtual ~CMMFDevSoundAdaptation();
sl@0: 
sl@0: public: // New functions
sl@0: 
sl@0: 	/*
sl@0: 	2nd phase open.
sl@0: 	Async open - if returns successfully, then will result in AsynchronousOperationComplete()
sl@0: 	*/
sl@0: 	IMPORT_C void PostOpenL();
sl@0: 
sl@0: 	/**
sl@0: 	* Initializes to raw audio data PCM16 and Sampling Rate of 8 KHz.
sl@0: 	* On completion of Initialization, calls InitializeComplete() on
sl@0: 	* aDevSoundObserver.
sl@0: 	* Leaves on failure.
sl@0: 	* @since
sl@0: 	* @param MDevSoundAdaptationObserver& aDevSoundObserver A reference to DevSound
sl@0: 	*        Observer instance.
sl@0: 	* @param TMMFState aMode Mode for which this object will be used.
sl@0: 	* @return void
sl@0: 	*/
sl@0: 	IMPORT_C void InitializeL(TMMFState aMode);
sl@0: 
sl@0: 	/**
sl@0: 	* Initializes DevSound object for the mode aMode for processing audio
sl@0: 	* data with hardware device aHWDev.
sl@0: 	* On completion of Initialization, calls InitializeComplete() on
sl@0: 	* aDevSoundObserver.
sl@0: 	* Leaves on failure.
sl@0: 	* @since
sl@0: 	* @param MDevSoundAdaptationObserver& aDevSoundObserver A reference to DevSound
sl@0: 	*        Observer instance.
sl@0: 	* @param TUid aHWDev The CMMFHwDevice implementation identifier.
sl@0: 	* @param TMMFState aMode The mode for which this object will be used
sl@0: 	* @return void
sl@0: 	*/
sl@0: 	IMPORT_C void InitializeL(TUid aHWDev,
sl@0: 							  TMMFState aMode);
sl@0: 
sl@0: 	/**
sl@0: 	* Initializes DevSound object for the mode aMode for processing audio
sl@0: 	* data with hardware device supporting FourCC aDesiredFourCC.
sl@0: 	* Leaves on failure.
sl@0: 	* @since
sl@0: 	* @param MDevSoundAdaptationObserver& aDevSoundObserver A reference to DevSound
sl@0: 	*        Observer instance.
sl@0: 	* @param TFourCC aDesiredFourCC The CMMFHwDevice implementation FourCC
sl@0: 	*        code.
sl@0: 	* @param TMMFState aMode The mode for which this object will be used
sl@0: 	* @return KErrNone if successfull, else corresponding error code
sl@0: 	* @return void
sl@0: 	*/
sl@0: 	IMPORT_C void InitializeL(TFourCC aDesiredFourCC,
sl@0: 							  TMMFState aMode);
sl@0: 
sl@0: 	/**
sl@0: 	* Cancels the initialization of a DevSound object.
sl@0: 	* @since
sl@0: 	* @return An error code indicating if the function call was successful.
sl@0: 	*   	  KErrNone on success,
sl@0: 	*		  KerrNotReady if this is called before InitializeL() call or after
sl@0: 	*		  the object has been initialized,
sl@0: 	*/
sl@0: 	IMPORT_C TInt CancelInitialize();
sl@0: 
sl@0: 	/**
sl@0: 	* Returns the supported Audio settings ie. encoding, sample rates,
sl@0: 	* mono/stereo operation, buffer size etc..
sl@0: 	* @since
sl@0: 	* @return TMMFCapabilities The device settings.
sl@0: 	*/
sl@0: 	IMPORT_C TInt Capabilities(TMMFCapabilities& aCap);
sl@0: 
sl@0: 	/**
sl@0: 	* Returns the current device configuration.
sl@0: 	* @since
sl@0: 	* @return TMMFCapabilities The device settings.
sl@0: 	*/
sl@0: 	IMPORT_C TMMFCapabilities Config() const;
sl@0: 
sl@0: 	/**
sl@0: 	* Configure CMMFDevSound object with the settings in aConfig. Use this
sl@0: 	* to set sampling rate, encoding and mono/stereo.
sl@0: 	* Leaves on failure.
sl@0: 	* @since
sl@0: 	* @param const TMMFCapabilities& aConfig The attribute values to which
sl@0: 	*        CMMFDevSound object will be configured to.
sl@0: 	* @return void
sl@0: 	*/
sl@0: 	IMPORT_C void SetConfigL(const TMMFCapabilities& aCaps);
sl@0: 
sl@0: 	/**
sl@0: 	* Returns an integer representing the maximum volume device supports.
sl@0: 	* This is the maximum value which can be passed to
sl@0: 	* CMMFDevSound::SetVolume.
sl@0: 	* @since
sl@0: 	* @return TInt The maximum volume. This value is platform dependent but
sl@0: 	*        is always greater than or equal to one.
sl@0: 	*/
sl@0: 	IMPORT_C TInt MaxVolume();
sl@0: 
sl@0: 	/**
sl@0: 	* Returns an integer representing the current volume.
sl@0: 	* @since
sl@0: 	* @return TInt The current volume level.
sl@0: 	*/
sl@0: 	IMPORT_C TInt Volume();
sl@0: 
sl@0: 	/**
sl@0: 	* Changes the current playback volume to a specified value. The volume
sl@0: 	* can be changed before or during playback and is effective immediately.
sl@0: 	* @since
sl@0: 	* @param TInt aVolume The volume setting. This can be any value from 0
sl@0: 	*        to the value returned by a call to
sl@0: 	*        CMMFDevSound::MaxVolume(). If the volume is not
sl@0: 	*        within this range, the volume is automatically set
sl@0: 	*        to minimum or maximum value based on the value
sl@0: 	*        that is being passed. Setting a zero value mutes
sl@0: 	*        the sound. Setting the maximum value results in
sl@0: 	*        the loudest possible sound.
sl@0: 	* @param aAsyncCompletion Returns ETrue to say the call is asynchronous, with result sent
sl@0: 	*        to AsynchronousOperationComplete()
sl@0: 	* @return KErrNone if successful, otherwise system-wide error code
sl@0: 	*/
sl@0: 	IMPORT_C TInt SetVolume(TInt aVolume, TBool& aAyncCompletion);
sl@0: 
sl@0: 	/**
sl@0: 	* Returns an integer representing the maximum gain the device supports.
sl@0: 	* This is the maximum value which can be passed to CMMFDevSound::SetGain
sl@0: 	* @since
sl@0: 	* @return TInt The maximum gain. This value is platform dependent but is
sl@0: 	*        always greater than or equal to one.
sl@0: 	*/
sl@0: 	IMPORT_C TInt MaxGain();
sl@0: 
sl@0: 	/**
sl@0: 	* Returns an integer representing the current gain.
sl@0: 	* @since
sl@0: 	* @return TInt The current gain level.
sl@0: 	*/
sl@0: 	IMPORT_C TInt Gain();
sl@0: 
sl@0: 	/**
sl@0: 	* Changes the current recording gain to a specified value. The gain can
sl@0: 	* be changed before or during recording and is effective immediately.
sl@0: 	* @since
sl@0: 	* @param TInt aGain The gain setting. This can be any value from zero to
sl@0: 	*        the value returned by a call to
sl@0: 	*        CMMFDevSound::MaxGain(). If the volume
sl@0: 	*        is not within this range, the gain is automatically
sl@0: 	*        set to minimum or maximum value based on the value
sl@0: 	*        that is being passed. Setting a zero value mutes the
sl@0: 	*        sound. Setting the maximum value results in the
sl@0: 	*        loudest possible sound.
sl@0: 	* @param aAsyncCompletion Returns ETrue to say the call is asynchronous, with result sent
sl@0: 	*        to AsynchronousOperationComplete()
sl@0: 	* @return KErrNone if successful, otherwise system-wide error code
sl@0: 	*/
sl@0: 	IMPORT_C TInt SetGain(TInt aGain, TBool& aAyncCompletion);
sl@0: 
sl@0: 	/**
sl@0: 	* Returns the speaker balance set for playing.
sl@0: 	* Leaves on failure.
sl@0: 	* @since
sl@0: 	* @param TInt &aLeftPercentage On return contains the left speaker
sl@0: 	*        volume percentage.
sl@0: 	* @param TInt &aRightPercentage On return contains the right speaker
sl@0: 	*        volume percentage.
sl@0: 	* @return void
sl@0: 	*/
sl@0: 	IMPORT_C void GetPlayBalanceL(TInt& aLeftPercentage, TInt& aRightPercentage);
sl@0: 
sl@0: 	/**
sl@0: 	* Sets the speaker balance for playing. The speaker balance can be
sl@0: 	* changed before or during playback and is effective immediately.
sl@0: 	* Leaves on failure.
sl@0: 	* @since
sl@0: 	* @param TInt aLeftPercentage The left speaker volume percentage. This
sl@0: 	*        can be any value from zero to 100. Setting
sl@0: 	*        a zero value mutes the sound on left
sl@0: 	*        speaker.
sl@0: 	* @param TInt aRightPercentage The right speaker volume percentage.
sl@0: 	*        This can be any value from zero to 100.
sl@0: 	*        Setting a zero value mutes the sound on
sl@0: 	*        right speaker.
sl@0: 	* @param aAsyncCompletion Returns ETrue to say the call is asynchronous, with result sent
sl@0: 	*        to AsynchronousOperationComplete()
sl@0: 	* @return void
sl@0: 	*/
sl@0: 	IMPORT_C void SetPlayBalanceL(TInt aLeftPercentage, TInt aRightPercentage, TBool& aAyncCompletion);
sl@0: 
sl@0: 	/**
sl@0: 	* Returns the microphone gain balance set for recording.
sl@0: 	* Leaves on failure.
sl@0: 	* @since
sl@0: 	* @param TInt &aLeftPercentage On return contains the left microphone
sl@0: 	*        gain percentage.
sl@0: 	* @param TInt &aRightPercentage On return contains the right microphone
sl@0: 	*        gain percentage.
sl@0: 	* @return void
sl@0: 	*/
sl@0: 	IMPORT_C void GetRecordBalanceL(TInt& aLeftPercentage, TInt& aRightPercentage);
sl@0: 
sl@0: 	/**
sl@0: 	* Sets the microphone balance for recording. The microphone balance can
sl@0: 	* be changed before or during recording and is effective immediately.
sl@0: 	* Leaves on failure.
sl@0: 	* @since
sl@0: 	* @param TInt aLeftPercentage The left microphone gain percentage. This
sl@0: 	*        can be any value from zero to 100. Setting
sl@0: 	*        a zero value mutes the sound from left
sl@0: 	*        microphone.
sl@0: 	* @param TInt aRightPercentage The right microphone gain percentage.
sl@0: 	*        This can be any value from zero to 100.
sl@0: 	*        Setting a zero value mutes the sound from
sl@0: 	*        right microphone.
sl@0: 	* @param aAsyncCompletion Returns ETrue to say the call is asynchronous, with result sent
sl@0: 	*        to AsynchronousOperationComplete()
sl@0: 	* @return void
sl@0: 	*/
sl@0: 	IMPORT_C void SetRecordBalanceL(TInt aLeftPercentage, TInt aRightPercentage, TBool& aAyncCompletion);
sl@0: 
sl@0: 	/**
sl@0: 	* Initializes the audio device and starts the play process. This
sl@0: 	* function queries and acquires the audio policy before initializing
sl@0: 	* audio device. If there was an error during policy initialization,
sl@0: 	* PlayError() function will be called on the observer with error code
sl@0: 	* KErrAccessDenied, otherwise BufferToBeFilled() function will be called
sl@0: 	* with a buffer reference. After reading data into the buffer reference
sl@0: 	* passed, the client should call PlayData() to play data.
sl@0: 	* The amount of data that can be played is specified in
sl@0: 	* CMMFBuffer::RequestSize(). Any data that is read into buffer beyond
sl@0: 	* this size will be ignored.
sl@0: 	* Leaves on failure.
sl@0: 	* @since
sl@0: 	* @return void
sl@0: 	*/
sl@0: 	IMPORT_C void PlayInitL();
sl@0: 
sl@0: 	/**
sl@0: 	* Initializes the audio device and starts the record process. This
sl@0: 	* function queries and acquires the audio policy before initializing
sl@0: 	* audio device. If there was an error during policy initialization,
sl@0: 	* RecordError() function will be called on the observer with error code
sl@0: 	* KErrAccessDenied, otherwise BufferToBeEmptied() function will be called
sl@0: 	* with a buffer reference. This buffer contains recorded or encoded
sl@0: 	* data. After processing data in the buffer reference passed, the client
sl@0: 	* should call RecordData() to continue recording process.
sl@0: 	* The amount of data that is available is specified in
sl@0: 	* CMMFBuffer::RequestSize().
sl@0: 	* Leaves on failure.
sl@0: 	* @since
sl@0: 	* @return void
sl@0: 	*/
sl@0: 	IMPORT_C void RecordInitL();
sl@0: 
sl@0: 	/**
sl@0: 	* Plays data in the buffer at the current volume.
sl@0: 	* The client should fill the buffer with audio data before calling this
sl@0: 	* function. The observer gets a reference to the buffer along with the
sl@0: 	* callback function BufferToBeFilled(). When playing of the audio sample
sl@0: 	* is complete, successfully or otherwise, the function PlayError() on
sl@0: 	* the observer is called.
sl@0: 	* The last buffer of the audio stream being played should have the last
sl@0: 	* buffer flag set using CMMFBuffer::SetLastBuffer(TBool). If a
sl@0: 	* subsequent attempt to play the clip is made, this flag will need
sl@0: 	* resetting by the client.
sl@0: 	* @return void
sl@0: 	*/
sl@0: 	IMPORT_C void PlayData();
sl@0: 
sl@0: 	/**
sl@0: 	* Contine the process of recording.
sl@0: 	* Once the buffer is filled with recorded data, the Observer gets a
sl@0: 	* reference to the buffer along with the callback function
sl@0: 	* BufferToBeEmptied(). After processing the buffer (copying over to a
sl@0: 	* different buffer or writing to file) the client should call this
sl@0: 	* function to continue the recording process.
sl@0: 	* @return void
sl@0: 	*/
sl@0: 	IMPORT_C void RecordData();
sl@0: 
sl@0: 	/**
sl@0: 	* Stops the ongoing operation (Play, Record, TonePlay).
sl@0: 	* @since
sl@0: 	* @return KErrNone if successful, system wide error otherwise
sl@0: 	*/
sl@0: 	IMPORT_C TBool Stop();
sl@0: 
sl@0: 	/**
sl@0: 	* Temporarily Stops the ongoing operation (Play, Record, TonePlay).
sl@0: 	* @since
sl@0: 	* @return KErrNone if successful, system wide error otherwise
sl@0: 	*/
sl@0: 	IMPORT_C TInt Pause();
sl@0: 
sl@0: 	/**
sl@0: 	* Returns the Sample recorded so far
sl@0: 	* @since
sl@0: 	* @return TInt Returns the samples recorded.
sl@0: 	*/
sl@0: 	IMPORT_C TInt SamplesRecorded();
sl@0: 
sl@0: 	/**
sl@0: 	* Returns the Sample played so far
sl@0: 	* @since
sl@0: 	* @return TInt Returns the samples played.
sl@0: 	*/
sl@0: 	IMPORT_C TInt SamplesPlayed();
sl@0: 
sl@0: 	/**
sl@0: 	* Initializes the audio device and starts playing a tone. The tone is
sl@0: 	* played with the frequency and duration specified.
sl@0: 	* Leaves on failure.
sl@0: 	* @since
sl@0: 	* @param TInt aFrequency The frequency at which the tone will be played.
sl@0: 	* @param const TTimeIntervalMicroSeconds &aDuration The period over
sl@0: 	*        which the tone will be played. A zero value causes the no tone
sl@0: 	*        to be played.
sl@0: 	* @return void
sl@0: 	*/
sl@0: 	IMPORT_C void PlayToneL(TInt aFrequency, const TTimeIntervalMicroSeconds& aDuration);
sl@0: 
sl@0: 	/**
sl@0: 	* Initializes audio device and starts playing a dual tone. Dual Tone is
sl@0: 	* played with the specified frequencies and for the specified duration.
sl@0: 	* Leaves on failure.
sl@0: 	* @since
sl@0: 	* @param TInt aFrequencyOne The first frequency of dual tone.
sl@0: 	* @param TInt aFrequencyTwo The second frequency of dual tone.
sl@0: 	* @param const TTimeIntervalMicroSeconds &aDuration The period over
sl@0: 	*        which the tone will be played. A zero value causes the no tone
sl@0: 	*        to be played.
sl@0: 	* @return void
sl@0: 	*/
sl@0: 	IMPORT_C void PlayDualToneL(TInt aFrequencyOne,
sl@0: 								TInt aFrequencyTwo,
sl@0: 								const TTimeIntervalMicroSeconds& aDuration);
sl@0: 
sl@0: 	/**
sl@0: 	* Initializes the audio device and starts playing the DTMF string
sl@0: 	* aDTMFString.
sl@0: 	* Leaves on failure.
sl@0: 	* @since
sl@0: 	* @param const TDesC &aDTMFString The DTMF sequence in a descriptor.
sl@0: 	* @return void
sl@0: 	*/
sl@0: 	IMPORT_C void PlayDTMFStringL(const TDesC& aDTMFString);
sl@0: 
sl@0: 	/**
sl@0: 	* Initializes the audio device and starts playing a tone sequence.
sl@0: 	* Leaves on failure.
sl@0: 	* @since
sl@0: 	* @param const TDesC8 &aData The tone sequence in a descriptor.
sl@0: 	* @return void
sl@0: 	*/
sl@0: 	IMPORT_C void PlayToneSequenceL(const TDesC8& aData);
sl@0: 
sl@0: 	/**
sl@0: 	* Initializes the audio device and starts playing the specified
sl@0: 	* pre-defined tone sequence.
sl@0: 	* Leaves on failure.
sl@0: 	* @since
sl@0: 	* @param TInt aSequenceNumber The index identifying the specific
sl@0: 	*        pre-defined tone sequence. Index values are relative to zero.
sl@0: 	*        This can be any value from zero to the value returned by a call
sl@0: 	*        to FixedSequenceCount() - 1. The function raises a panic if the
sl@0: 	*        sequence number is not within this range.
sl@0: 	* @return void
sl@0: 	*/
sl@0: 	IMPORT_C void PlayFixedSequenceL(TInt aSequenceNumber);
sl@0: 
sl@0: 	/**
sl@0: 	* Defines the number of times the audio is to be repeated during the
sl@0: 	* tone playback operation. A period of silence can follow each playing
sl@0: 	* of a tone. The tone playing can be repeated indefinitely
sl@0: 	* @since
sl@0: 	* @param TInt aRepeatCount The number of times the tone, together with
sl@0: 	*        the trailing silence, is to be repeated. If this is set to
sl@0: 	*        KMdaRepeatForever, then the tone, together with the trailing
sl@0: 	*        silence, is repeated indefinitely or until Stop() is called.
sl@0: 	*        If this is set to zero, then the tone is not repeated.
sl@0: 	* @param const TTimeIntervalMicroSeconds &aRepeatTrailingSilence An
sl@0: 	*        interval of silence which will be played after each tone.
sl@0: 	*        Supported only during tone playing.
sl@0: 	* @return KErrNone if successful, system wide error otherwise
sl@0: 	*/
sl@0: 	IMPORT_C TInt SetToneRepeats(TInt aRepeatCount,
sl@0: 				  const TTimeIntervalMicroSeconds& aRepeatTrailingSilence);
sl@0: 
sl@0: 	/**
sl@0: 	* Defines the duration of tone on, tone off and tone pause to be used
sl@0: 	* during the DTMF tone playback operation.
sl@0: 	* Supported only during tone playing.
sl@0: 	* @since
sl@0: 	* @param TTimeIntervalMicroSeconds32 &aToneOnLength The period over
sl@0: 	*        which the tone will be played. If this is set to zero, then the
sl@0: 	*        tone is not played.
sl@0: 	* @param TTimeIntervalMicroSeconds32 &aToneOffLength The period over
sl@0: 	*        which the no tone will be played.
sl@0: 	* @param TTimeIntervalMicroSeconds32 &aPauseLength The period over which
sl@0: 	*        the tone playing will be paused.
sl@0: 	* @return KErrNone if successful, system wide error otherwise
sl@0: 	*/
sl@0: 	IMPORT_C TInt SetDTMFLengths(TTimeIntervalMicroSeconds32& aToneOnLength,
sl@0: 								 TTimeIntervalMicroSeconds32& aToneOffLength,
sl@0: 								 TTimeIntervalMicroSeconds32& aPauseLength);
sl@0: 
sl@0: 	/**
sl@0: 	* Defines the period over which the volume level is to rise smoothly
sl@0: 	* from nothing to the normal volume level.
sl@0: 	* The function is only available before playing.
sl@0: 	* @since
sl@0: 	* @param const TTimeIntervalMicroSeconds &aRampDuration The period over
sl@0: 	*        which the volume is to rise. A zero value causes the tone
sl@0: 	*        sample to be played at the normal level for the full duration
sl@0: 	*        of the playback. A value, which is longer than the duration of
sl@0: 	*        the tone sample means that the sample never reaches its normal
sl@0: 	*        volume level.
sl@0: 	* @return KErrNone if successful, system wide error otherwise
sl@0: 	*/
sl@0: 	IMPORT_C TInt SetVolumeRamp(const TTimeIntervalMicroSeconds& aRampDuration);
sl@0: 
sl@0: 	/**
sl@0: 	* Defines the priority settings that should be used for this instance.
sl@0: 	* @since
sl@0: 	* @param const TMMFPrioritySettings &aPrioritySettings A class type
sl@0: 	*        representing the client's priority, priority preference and
sl@0: 	*        state
sl@0: 	* @return KErrNone if successful, system wide error otherwise
sl@0: 	*/
sl@0: 	IMPORT_C TInt SetPrioritySettings(
sl@0: 				  const TMMFPrioritySettings& aPrioritySettings);
sl@0: 
sl@0: 	/**
sl@0: 	* Retrieves a custom interface to the device.
sl@0: 	* @since
sl@0: 	* @param TUid aInterfaceId The interface UID, defined with the custom
sl@0: 	*        interface.
sl@0: 	* @return TAny* A pointer to the interface implementation, or NULL if
sl@0: 	*        the device does not implement the interface requested. The
sl@0: 	*        return value must be cast to the correct type by the user.
sl@0: 	*/
sl@0: 	IMPORT_C TAny* CustomInterface(TUid aInterfaceId);
sl@0: 
sl@0: 	/**
sl@0: 	* Returns the number of available pre-defined tone sequences.
sl@0: 	* This is the number of fixed sequence supported by DevSound by default.
sl@0: 	* @since
sl@0: 	* @return TInt  The fixed sequence count. This value is implementation
sl@0: 	*        dependent.
sl@0: 	*/
sl@0: 	IMPORT_C TInt FixedSequenceCount();
sl@0: 
sl@0: 	/**
sl@0: 	* Returns the name assigned to a specific pre-defined tone sequence.
sl@0: 	* This is the number of the fixed sequence supported by DevSound by
sl@0: 	* default.
sl@0: 	* The function raises a panic if sequence number specified is invalid.
sl@0: 	* @since
sl@0: 	* @param TInt aSequenceNumber The index identifying the specific
sl@0: 	*        pre-defined tone sequence. Index values are relative to zero.
sl@0: 	*        This can be any value from zero to the value returned by a call
sl@0: 	*        to CMdaAudioPlayerUtility::FixedSequenceCount() - 1. The
sl@0: 	*        function raises a panic if sequence number is not within this
sl@0: 	*        range.
sl@0: 	* @return const TDesC & A reference to a Descriptor containing the fixed
sl@0: 	*        sequence name indexed by aSequenceNumber.
sl@0: 	*/
sl@0: 	IMPORT_C const TDesC& FixedSequenceName(TInt aSequenceNumber);
sl@0: 
sl@0: 	/**
sl@0: 	* Returns a list of the supported input datatypes that can be sent to
sl@0: 	* DevSound for playing audio. The datatypes returned are those that the
sl@0: 	* DevSound supports given the priority settings passed in
sl@0: 	* aPrioritySettings. Note that if no supported data types are found this
sl@0: 	* does not constitute failure, the function will return normally with no
sl@0: 	* entries in aSupportedDataTypes.
sl@0: 	* @since
sl@0: 	* @param RArray< TFourCC > &aSupportedDataTypes The array of supported
sl@0: 	*        data types that will be filled in by this function. The
sl@0: 	*        supported data types of the DevSound are in the form of an
sl@0: 	*        array of TFourCC codes. Any existing entries in the array will
sl@0: 	*        be overwritten on calling this function. If no supported data
sl@0: 	*        types are found given the priority settings, then the
sl@0: 	*        aSupportedDatatypes array will have zero entries.
sl@0: 	* @param const TMMFPrioritySettings &aPrioritySettings The priority
sl@0: 	*        settings used to determine the supported datatypes. Note this
sl@0: 	*        does not set the priority settings. For input datatypes the
sl@0: 	*        iState member of the priority settings would be expected to be
sl@0: 	*        either EMMFStatePlaying or EMMFStatePlayingRecording. The
sl@0: 	*        priority settings may effect the supported datatypes depending
sl@0: 	*        on the audio routing.
sl@0: 	* @return void
sl@0: 	*/
sl@0: 	IMPORT_C void GetSupportedInputDataTypesL(
sl@0: 				  RArray<TFourCC>& aSupportedDataTypesconst,
sl@0: 				  const TMMFPrioritySettings& aPrioritySettings) const;
sl@0: 
sl@0: 	/**
sl@0: 	* Returns a list of the supported output dataypes that can be received
sl@0: 	* from DevSound for recording audio. The datatypes returned are those
sl@0: 	* that the DevSound supports given the priority settings passed in
sl@0: 	* aPrioritySettings. Note that if no supported data types are found this
sl@0: 	* does not constitute failure, the function will return normally with no
sl@0: 	* entries in aSupportedDataTypes.
sl@0: 	* @since
sl@0: 	* @param RArray< TFourCC > &aSupportedDataTypes The array of supported
sl@0: 	*        data types that will be filled in by this function. The
sl@0: 	*        supported datatypes of the DevSound are in the form of an array
sl@0: 	*        of TFourCC codes. Any existing entries in the array will be
sl@0: 	*        overwritten on calling this function. If no supported datatypes
sl@0: 	*        are found given the priority settings, then the
sl@0: 	*        aSupportedDatatypes array will have zero entries.
sl@0: 	* @param const TMMFPrioritySettings &aPrioritySettings The priority
sl@0: 	*        settings used to determine the supported data types. Note this
sl@0: 	*        does not set the priority settings. For output data types the
sl@0: 	*        iState member of the priority settings would expected to be
sl@0: 	*        either EMMFStateRecording or EMMFStatePlayingRecording. The
sl@0: 	*        priority settings may effect the supported datatypes depending
sl@0: 	*        on the audio routing.
sl@0: 	* @return void
sl@0: 	*/
sl@0: 	IMPORT_C void GetSupportedOutputDataTypesL(
sl@0: 				  RArray<TFourCC>& aSupportedDataTypes,
sl@0: 				  const TMMFPrioritySettings& aPrioritySettings) const;
sl@0: 
sl@0: 	/**
sl@0: 	* Sets client configuration
sl@0: 	* @since
sl@0:     * @param aActualProcessId the effective devsound client (supplied with SetClientThreadInfo)
sl@0:     * @param aProcessId the client of DevSound
sl@0: 	* @return KErrNone if successful, system wide error otherwise
sl@0: 	*/
sl@0:     IMPORT_C TInt SetClientConfig(const TProcessId& aProcessId);
sl@0:     IMPORT_C TInt SetClientConfig(const TProcessId& aActualProcessId, const TProcessId& aProcessId);
sl@0: 
sl@0: 	/**
sl@0: 	* Empties the buffers below DevSound without deleting the codec.
sl@0: 	* @since
sl@0: 	* @return KErrNone if successful, otherwise system-wide error code.
sl@0: 	*/
sl@0: 	IMPORT_C TInt EmptyBuffers();
sl@0: 
sl@0: 	/*
sl@0: 	* Make sure any deletions is commited
sl@0: 	* @since
sl@0: 	* @
sl@0: 	*
sl@0: 	*/
sl@0: 	IMPORT_C TBool CloseDevSound();
sl@0: 
sl@0: 	/**
sl@0: 	* Called when a ProcessingFinished callback is received
sl@0: 	* @since
sl@0: 	* @param aAsyncCompletion Returns ETrue to say the call is asynchronous, with result sent
sl@0: 	*			to AsynchronousOperationComplete()
sl@0: 	* @return an error code KErrNone if successful
sl@0: 	*/
sl@0: 	IMPORT_C TInt ProcessingFinishedReceived(TBool& aAyncCompletion);
sl@0: 	
sl@0: 	IMPORT_C TInt ProcessingError(TBool& aAyncCompletion);
sl@0: 	
sl@0: 	//provides interface for register a notification event
sl@0: 	IMPORT_C TInt RegisterAsClient(TUid aEventType, const TDesC8& aNotificationRegistrationData = KNullDesC8);
sl@0: 	//provides interface to cancel the registered notification
sl@0: 	IMPORT_C TInt CancelRegisterAsClient(TUid aEventType);
sl@0: 	//Gets the notification data for client to resume
sl@0: 	IMPORT_C TInt GetResourceNotificationData(TUid aEventType, TDes8& aNotificationData);
sl@0: 	//waits for the client to resume playback even after the timeout expires
sl@0: 	IMPORT_C TInt WillResumePlay();
sl@0: 
sl@0: 	/**
sl@0: 	* Gets the current play time from the audio renderer
sl@0: 	* @since 
sl@0: 	* @param TTimeIntervalMicroSeconds& aTime On return contains the current play time
sl@0: 	* @return an error code KErrNone if successful
sl@0: 	*/
sl@0: 	IMPORT_C TInt GetTimePlayed(TTimeIntervalMicroSeconds& aTime);
sl@0: 
sl@0: 	/**
sl@0: 	* Queries if the low layers does support resume operation.
sl@0: 	* @since
sl@0: 	* @return TBool ETrue if Resume is supported
sl@0: 	*               EFalse otherwise
sl@0: 	*/
sl@0: 	IMPORT_C TBool IsResumeSupported();
sl@0: 	
sl@0: 	/**
sl@0: 	* Resume the operation (Play, Record, TonePlay) temporarily paused .
sl@0: 	* @since
sl@0: 	* @return TInt KErrNone if succesful
sl@0: 	*              KErrNotSupported if the operation is not supported by this implementation
sl@0: 	*/
sl@0: 	IMPORT_C TInt Resume();
sl@0: 
sl@0: 	/*
sl@0: 	Used to send a stop call when error in buffer
sl@0: 	*/
sl@0: 	IMPORT_C void BufferErrorEvent();
sl@0: 	
sl@0: 	/**
sl@0: 	* Used rollback the adapror active state to the previous state prior a Commit call
sl@0: 	* @return void
sl@0: 	*/
sl@0: 	IMPORT_C void RollbackAdaptorActiveStateToBeforeCommit();
sl@0: 
sl@0: protected:
sl@0: 
sl@0: 	// So that nobody can extend
sl@0: 	CMMFDevSoundAdaptation();
sl@0: 
sl@0: 	// Second phase constructor
sl@0: 	void ConstructL(MDevSoundAdaptationObserver& aDevSoundObserver,
sl@0: 				MGlobalProperties& aGlobalProperties);
sl@0: 
sl@0: protected:  // Data
sl@0: 	// Actual implementation class.
sl@0: 	class CBody;
sl@0: 
sl@0: 	//DevSoundAdaptation body implementation
sl@0: 	CBody* iBody;
sl@0: 	};
sl@0: 
sl@0: #endif      // MMFDEVSOUNDADAPTATION
sl@0: 
sl@0: // End of File