// Copyright (c) 2001-2009 Nokia Corporation and/or its subsidiary(-ies).

// All rights reserved.

// This component and the accompanying materials are made available

// which accompanies this distribution, and is available

//

// Initial Contributors:

// Nokia Corporation - initial contribution.

//

// Contributors:

//

// Description:

//

#ifndef __SOUNDDEVICE_H__

#define __SOUNDDEVICE_H__

#include <e32base.h>

#include <f32file.h>

#include <mmf/common/mmfbase.h>

#include <mmf/common/mmfutilities.h>

#include <mmf/common/mmfcontroller.h>

//Debugging info

/*

Notes: 

This file defines the DevSound class which acts as an interface to

the hardware and is intended to invoke VCR functionality via the plug-ins.

The DevSound also contains a product specific policy.

*/

//UIDs for buffers: According to Symbian: Not used

// Public Media Server includes

/**

@publishedAll

@released

Sampling rates available.

When queried from DevSound by calling the function Capabilities(), iRate indicates

the sampling rates supported by the audio device.

DevSound by default is configured to 8KHz sampling rate.

So to configure DevSound to play/record audio at 16 KHz sampling rate:

The mode should not be OR'ed with each other, only single values are accepted. 

*/

enum TMMFSampleRate

	{

  	/** 8000 Hz Sampling Rate

	*/

	EMMFSampleRate8000Hz  = 0x00000001,

  	/** 11025 Hz Sampling Rate

	*/

	EMMFSampleRate11025Hz = 0x00000002,

  	/** 16000 Hz Sampling Rate

	*/

	EMMFSampleRate16000Hz = 0x00000004,

  	/** 22050 Hz Sampling Rate

	*/

	EMMFSampleRate22050Hz = 0x00000008,

  	/** 32000 Hz Sampling Rate

	*/

	EMMFSampleRate32000Hz = 0x00000010,

  	/** 44100 Hz Sampling Rate

	*/

	EMMFSampleRate44100Hz = 0x00000020,

  	/** 48000 Hz Sampling Rate

	*/

	EMMFSampleRate48000Hz = 0x00000040,

  	/** 88200 Hz Sampling Rate

	*/

	EMMFSampleRate88200Hz = 0x00000080,

  	/** 96000 Hz Sampling Rate

	*/

	EMMFSampleRate96000Hz = 0x00000100,

  	/** 12000 Hz Sampling Rate

	*/

	EMMFSampleRate12000Hz = 0x00000200,

  	/** 24000 Hz Sampling Rate

	*/

	EMMFSampleRate24000Hz = 0x00000400,

  	/** 64000 Hz Sampling Rate

	*/

	EMMFSampleRate64000Hz = 0x00000800

	};

/**

@publishedAll

@released

Mono Stereo playback and record modes available.

When queried from DevSound by calling the function Capabilities(), iChannels

indicates whether the underlying audio device supports playing back stereo

audio samples and recording audio samples in stereo mode or not.

DevSound by default is configured to Mono mode.

So to configure DevSound to play/record audio sample in stereo mode:

The mode should not be OR'ed with each other, only single values are accepted. 

*/

enum TMMFMonoStereo

	{

	/** Mono mode

	*/

	EMMFMono	= 0x00000001,

	/** Stereo mode

	*/

	EMMFStereo	= 0x00000002

	};

/**

@publishedAll

@released

Encoding modes available.

When queried from DevSound by calling the function Capabilities(), iEncoding

provides information about different encoding supported by audio device.

DevSound by default is configured to play PCM16 Bit audio data.

Setting encoding mode is not supported yet:

*/

enum TMMFSoundEncoding

	{

  	/** Signed 8 Bit PCM

	*/

	EMMFSoundEncoding8BitPCM		= 0x00000001,

  	/** Signed 16 Bit PCM

	*/

	EMMFSoundEncoding16BitPCM		= 0x00000002,

  	/** Signed 8 Bit ALaw

	*/

	EMMFSoundEncoding8BitALaw		= 0x00000004,

  	/** Signed 8 Bit MuLaw

	*/

	EMMFSoundEncoding8BitMuLaw		= 0x00000008,

	};

/**

@publishedAll

@released

Stereo support enum.

*/

enum TMMFStereoSupport

	{

	/** No stereo support

	*/

	EMMFNone						= 0x00000000,

	/** Interleaved stereo support

	*/

	EMMFInterleavedOnly				= 0x00000001,

	/** Non Interleaved stereo support

	*/

	EMMFNonInterleavedOnly			= 0x00000002,

	/** Interleaved and Non Interleaved stereo support

	*/

	EMMFBothNonAndInterleaved		= 0x00000003,

 	/** Joint stereo support

 	*/

 	EMMFJoint						= 0x00000004

	};

/**

@publishedAll

@released

Type class for DevSound implementation device capabilities.

CMMFDevSound will return Sampling Rates, Encoding and Stereo feature

supported in this structure when queried for capabilities. DevSound can

also be configured by setting parameters in this structure and passing the

structure to it.

*/

class TMMFCapabilities

	{

public:

	/** Sampling Rates supported

	*/

	TUint	iRate;

	/** Encodings supported

	*/

	TUint	iEncoding;

	/** Mono/Stereo support

	*/

	TUint	iChannels;

	/** Buffer size supported

	*/

	TInt	iBufferSize;

	};

/**

@publishedAll

@released

An interface to a set of DevSound callback functions.

This serves as the method of communication between the client and the

DevSound.

The class is a mixin and is intended to be inherited by the client class

that is interested in observing the DevSound operation. The functions

encapsulated by this class are called when specific events occur in the

process of initializing and playing/recording an audio sample or playing

tones.

*/

class MDevSoundObserver

	{

public:

	/**

	Handles initialization completion event.

	A derived class must provide an implementation to handle the initialization

	request.

	CMMFDevSound object calls this function when its InitializeL() function

	completes.

	@param  aError

	        Error code. KErrNone if successful. Other values are possible

	        indicating a problem initializing CMMFDevSound object.

	*/

	virtual void InitializeComplete(TInt aError)=0;

	/**

	Handles tone play completion event.

	A derived class must provide an implementation to handle the tone play

	completion request.

	CMMFDevSound object calls this function when an attempt to play tone has

	completed, successfully or otherwise.

	The following are the play tone functions; PlayToneL(), PlayDMTFStringL(),

	PlayToneSequenceL(), and PlayFixedSequenceL().

	@param	aError

	        Error code. The status of tone playback. KErrUnderflow playing of

	        the tone is complete. KErrAccessDenied the sound device is in use by

	        another higher priority client. KErrCancel playing of the audio

	        sample is stopped by DevSound client another higher priority client.

	*/

	virtual void ToneFinished(TInt aError)=0;

	/**

	Handles CMMFDevSound object's data request event.

	A derived class must provide an implementation to supply CMMFDevSound

	object the data that it needs to play or convert.

	CMMFDevSound object calls this function when and where it needs data for

	playing or converting. The observer should notify CMMFDevSound object as

	quickly as possible after the data is read into buffer, aBuffer by calling

	PlayData(), otherwise the implementation might callback function PlayError()

	on derived class object with error code KErrUnderflow.

	This does not apply to the very first call to PlayData(), however.

	It is possible for a user of DevSound to hold the first buffer sent in

	BufferToBeFilled() until ready to play.

	The use case for this is if a low latency audio response

	is required, as at this point all the resources used to play audio are open.

	If used in this way then it is important to be aware that when when the

	resources for audio are ready at the BufferToBeFilled() callback, a Devsound

	on a real device will be running at increased power consumption as the audio

	hw and any required DSPs will be powered up etc.

	@param  aBuffer

	        Buffer into which data should be read. The amount of data that is

	        needed is specified in CMMFBuffer::RequestSize().

	*/

	virtual void BufferToBeFilled(CMMFBuffer* aBuffer)=0;

	/**

	Handles play completion or cancel event.

	A derived class must provide an implementation to handle the play

	completion or cancel request.

	CMMFDevSound object calls this function when an attempt to play audio sample

	has completed, successfully or otherwise.

	@param  aError

	        Error code. The status of playback. KErrUnderflow playing of the

	        audio sample is complete. KErrAccessDenied the sound device is in

	        use by another higher priority client.

	*/

	virtual void PlayError(TInt aError)=0;

	/**

	Handles CMMFDevSound object's data request event.

	A derived class must provide an implementation to process the data

	supplied by CMMFDevSound object while recording or converting.

	CMMFDevSound object calls this function when the buffer, aBuffer gets filled

	while recording or converting. The observer should notify CMMFDevSound

	object as quickly as possible after data in the buffer is processed by

	calling RecordData(), otherwise the implementation might callback

	the function RecordError() on derived class object with error code KErrOverflow.

	@param  aBuffer

	        Buffer containing processed (recorded or converted) data. The amount

	        of data that is available is specified in CMMFBuffer::RequestSize().

	*/

	virtual void BufferToBeEmptied(CMMFBuffer* aBuffer)=0;

	/**

	Handles record completion or cancel event.

	A derived class must provide an implementation to handle the record

	completion or cancel request.

	CMMFDevSound object calls this function when an attempt to record audio sample

	has completed, successfully or otherwise.

	@param  aError

	        Error code. The status of recording. KErrOverflow audio devices

	        runs out of internal buffer. KErrAccessDenied the sound device is

	        in use by another higher priority client.

	*/

	virtual void RecordError(TInt aError)=0;

	/**

	Handles conversion completion or cancel event.

	A derived class must provide an implementation to handle the conversion

	completion or cancel request.

	CMMFDevSound object calls this function when an attempt to convert data from

	source format to destination format has completed, successfully or otherwise.

	@param  aError

	        Error code. KErrCancel conversion operation is cancelled. KErrNone

	        conversion is complete. Other values are possible indicating a

	        problem converting data.

	*/

	virtual void ConvertError(TInt aError)=0;

	/**

	Handles device event.

	A derived class must provide an implementtion to handle the messages from

	audio hardware device.

	CMMFDevSound object calls this function when a message is received from the

	audio hardware device.

	@param	aMessageType

			Defines the type of message. Used to determine how to

			interpret the contents of aMsg.

	@param	aMsg

			Message that is packed in the Descriptor format.

	*/

	virtual void DeviceMessage(TUid aMessageType, const TDesC8& aMsg)=0;

	/**

	Handles policy request completion event.

	A derived class must provide an implementation to handle the policy request

	completion event.

	CMMFDevSound object calls this function when an attempt to acquire sound

	device is rejected by audio policy server.

	@param	aEvent

			Not used

	*/

	inline virtual void SendEventToClient(const TMMFEvent& aEvent);

	};

/**

@publishedAll

@released

This is the interface from Symbian OS to the raw audio functions on the

device hardware.

DevSound is currently loaded as a DLL, and implements the VCR-type

functions to be expected for such an interface.

The audio functions include the following functionality:

- Initialisation and configuration of hardware devices, for example, setting microphone gain, 

setting setero balance and so on.

- The playing and recording of raw audio data.

- The playing and dynamic control of tones with user specified frequencies.

- The playing of DTMF strings.

*/

class CMMFDevSound : public CBase

	{

public:

	/**

	Constructs, and returns a pointer to, a new CMMFDevSound object.

	Leaves on failure.

	*/

	IMPORT_C static CMMFDevSound* NewL();

	/**

	Destructor.

	Deletes all objects and releases all resource owned by this

	instance.

	*/

	IMPORT_C ~CMMFDevSound();

	/**

	Initializes CMMFDevSound object to play and record PCM16 raw audio data

	with sampling rate of 8 KHz.

	On completion of Initialization, calls InitializeComplete() on

	aDevSoundObserver.

	Leaves on failure.

	@param  aDevSoundObserver

	        A reference to DevSound Observer instance.

	@param  aMode

	        The mode for which this object will be used. Any value other than EMMFStatePlaying, EMMFStateRecording or EMMFStateTonePlaying is unsupported. 

	*/

    IMPORT_C void InitializeL(MDevSoundObserver& aDevSoundObserver, TMMFState aMode);

	/**

	Initializes DevSound object for the mode aMode for processing audio data

	with hardware device aHWDev.

	On completion of Initialization, the observer will be notified via call back

	InitializeComplete().

	Leaves on failure.

	@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. Any value other than EMMFStatePlaying, EMMFStateRecording or EMMFStateTonePlaying is unsupported.

   	*/

	IMPORT_C void InitializeL(MDevSoundObserver& aDevSoundObserver, TUid aHWDev, TMMFState aMode);

	/**

	Initializes DevSound object for the mode aMode for processing audio data

	with hardware device supporting FourCC aDesiredFourCC.

	On completion of Initialization, the observer will be notified via call back

	InitializeComplete().

	Leaves on failure.

	@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. Any value other than EMMFStatePlaying, EMMFStateRecording or EMMFStateTonePlaying is unsupported.

    */

	IMPORT_C void InitializeL(MDevSoundObserver& aDevSoundObserver, TFourCC aDesiredFourCC, TMMFState aMode);

	/**

	Returns the supported Audio settings ie. encoding, sample rates, mono/stereo operation, buffer 

	size etc.

	@return	The device settings.

	*/

	IMPORT_C TMMFCapabilities Capabilities();

	/**

	Returns the current device configuration.

	@return	The device settings.

	*/

	IMPORT_C TMMFCapabilities Config() const;

	/**

	Configure CMMFDevSound object with the settings in aConfig.

	Use this to set sampling rate, encoding and mono/stereo.

	@param  aCaps

	        The attribute values to which CMMFDevSound object will be configured to.

	*/

	IMPORT_C void SetConfigL(const TMMFCapabilities& aCaps);

	/**

	Returns an integer representing the maximum volume device supports.

	This is the maximum value which can be passed to CMMFDevSound::SetVolume.

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

	to one.

	*/

	IMPORT_C TInt MaxVolume();

	/**

	Returns an integer representing the current volume.

	@return The current volume level.

	*/

	IMPORT_C TInt Volume();

	/**

	Changes the current playback volume to a specified value.

	The volume can be changed before or during playback and is effective

	immediately.

	@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.