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

// All rights reserved.

// This component and the accompanying materials are made available

// under the terms of the License "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:

// e32\include\d32soundsc.h

// User side class definition for the shared chunk sound driver.

// 

//

/**

 @file

 @publishedPartner

 @prototype

*/

#ifndef __D32SOUNDSC_H__

#define __D32SOUNDSC_H__

#include <e32cmn.h>

#include <e32ver.h>

#ifndef __KERNEL_MODE__

#include <e32std.h>

#endif

_LIT(KDevSoundScName,"SoundSc");

const TInt KSoundScTxUnit0=0;

const TInt KSoundScTxUnit1=1;

/**

@capability UserEnvironment

@ref RSoundSc::Open An RSoundSc may not be opened for record without UserEnvironment

*/

const TInt KSoundScRxUnit0=4;

/**

@capability UserEnvironment

@ref RSoundSc::Open An RSoundSc may not be opened for record without UserEnvironment

*/

const TInt KSoundScRxUnit1=5;

// Note that the implementation in the sound driver LDD to calculate a default audio configuration assumes a 

// monotonic ordering of all caps bitfields. If it is necessary to break this ordering then this implementation

// will need to be reviewed and possibly changed.

/**

Sound driver capability constants - bitmasks of the audio channel configurations supported

by a unit. @see TSoundFormatsSupportedV02.

*/

/** The unit supports Mono (i.e. a single audio channel). */

const TUint KSoundMonoChannel = 0x0001;

/** The unit supports Stereo (i.e. two audio channels). */

const TUint KSoundStereoChannel = 0x0002;

/** The unit supports three audio channels. */

const TUint KSoundThreeChannel = 0x0004;

/** The unit supports four audio channels. */

const TUint KSoundFourChannel = 0x0008;

/** The unit supports five audio channels. */

const TUint KSoundFiveChannel = 0x0010;

/** The unit supports six audio channels. */

const TUint KSoundSixChannel = 0x0020;

/**

Sound driver capability constants - bitmasks of supported sample rates. @see TSoundFormatsSupportedV02.

*/

/** The device supports the 7.35KHz sample rate. */

const TUint KSoundRate7350Hz = 0x0001;

/** The device supports the 8KHz sample rate. */

const TUint KSoundRate8000Hz = 0x0002;

/** The device supports the 8.82KHz sample rate. */

const TUint KSoundRate8820Hz = 0x0004;

/** The device supports the 9.6KHz sample rate. */

const TUint KSoundRate9600Hz = 0x0008;

/** The device supports the 11.025KHz sample rate. */

const TUint KSoundRate11025Hz = 0x0010;

/** The device supports the 12KHz sample rate. */

const TUint KSoundRate12000Hz = 0x0020;

/** The device supports the 14.7KHz sample rate. */

const TUint KSoundRate14700Hz = 0x0040;

/** The device supports the 16KHz sample rate. */

const TUint KSoundRate16000Hz = 0x0080;

/** The device supports the 22.05KHz sample rate. */

const TUint KSoundRate22050Hz = 0x0100;

/** The device supports the 24KHz sample rate. */

const TUint KSoundRate24000Hz = 0x0200;

/** The device supports the 29.4KHz sample rate. */

const TUint KSoundRate29400Hz = 0x0400;

/** The device supports the 32KHz sample rate. */

const TUint KSoundRate32000Hz = 0x0800;

/** The device supports the 44.1KHz sample rate. */

const TUint KSoundRate44100Hz = 0x1000;

/** The device supports the 48KHz sample rate. */

const TUint KSoundRate48000Hz = 0x2000;

/**

Sound driver capability constants - bitmasks of supported encoding formats. @see TSoundFormatsSupportedV02.

*/

/** The device supports 8bit PCM encoding format. */

const TUint KSoundEncoding8BitPCM = 0x0001;

/** The device supports 16bit PCM encoding format. */

const TUint KSoundEncoding16BitPCM = 0x0002;

/** The device supports 24bit PCM encoding format. */

const TUint KSoundEncoding24BitPCM = 0x0004;

/**

Sound driver capability constants - bitmasks of the data formats supported

by the device. @see TSoundFormatsSupportedV02.

*/

/** The device supports an interleaved data format (i.e. data for each channel is interleaved throughout

each data buffer). */

const TUint KSoundDataFormatInterleaved = 0x0001;

/** The device supports a non-interleaved data format (i.e. data for each channel is arranged in

contiguous regions within each data buffer). */

const TUint KSoundDataFormatNonInterleaved = 0x0002;

/** The maximum setting possible for the record level / volume. */

const TInt KSoundMaxVolume = 255;

/**

Enumeration of possible data transfer directions. @see TSoundFormatsSupportedV02.

*/

enum TSoundDirection

	{

	/**	A unit for recording data. */

	ESoundDirRecord,

	/** A unit for playing data. */

	ESoundDirPlayback

	};

/**

Enumeration of possible sample rates. @see TCurrentSoundFormatV02.

*/	

enum TSoundRate

	{

	/** 7.35KHz sample rate. */

	ESoundRate7350Hz,

	/** 8KHz sample rate. */

	ESoundRate8000Hz,

	/** 8.82KHz sample rate. */

	ESoundRate8820Hz,

	/** 9.6KHz sample rate. */

	ESoundRate9600Hz,

	/** 11.025KHz sample rate. */

	ESoundRate11025Hz,

	/** 12KHz sample rate. */

	ESoundRate12000Hz,

	/** 14.7KHz sample rate. */

	ESoundRate14700Hz,

	/** 16KHz sample rate. */

	ESoundRate16000Hz,

	/** 22.05KHz sample rate. */

	ESoundRate22050Hz,

	/** 24KHz sample rate. */

	ESoundRate24000Hz,

	/** 29.4KHz sample rate. */

	ESoundRate29400Hz,

	/** 32KHz sample rate. */

	ESoundRate32000Hz,

	/** 44.1KHz sample rate. */

	ESoundRate44100Hz,

	/** 48KHz sample rate. */

	ESoundRate48000Hz

	};

/**

Enumeration of possible sound encoding formats. @see TCurrentSoundFormatV02.

*/

enum TSoundEncoding

	{

	/** 8bit PCM encoding format. */

	ESoundEncoding8BitPCM,

	/** 16bit PCM encoding format. */

	ESoundEncoding16BitPCM,

	/** 24bit PCM encoding format. */

	ESoundEncoding24BitPCM

	};

/**

Enumeration of possible sound data formats. @see TCurrentSoundFormatV02.

*/

enum TSoundDataFormat

	{

	/** The device supports an interleaved data format. */ 

	ESoundDataFormatInterleaved,

	/** The device supports a non-interleaved data format. */

	ESoundDataFormatNonInterleaved

	};	

/**

The general driver capabilites class - returned by the LDD factory in response to RDevice::GetCaps().

*/

class TCapsSoundScV01

	{

public:

	TVersion iVersion;

	};

/**

The main audio capabilities class. This is used by the LDD to get either the play or record capabilities

of a particular sound device once a channel to it has been opened.

*/

class TSoundFormatsSupportedV02

	{

public:

	/** The data transfer direction for this unit: play or record. @see TSoundDirection. */

	TSoundDirection iDirection;

	/** The audio channel configurations supported by this unit - a bitfield. */

	TUint32 iChannels;

	/** The sample rates supported - a bitfield. */

	TUint32 iRates;

	/** The encoding formats supported - a bitfield. */

	TUint32 iEncodings;

	/** The data formats supported - a bitfield. */

	TUint32 iDataFormats;

	/** The minimum request size that the device can support. All requests to play or record data must be of a

	length that is a multiple of this value. */

	TInt iRequestMinSize;

	/** The logarithm to base 2 of the alignment required for request arguments. All requests to play or

	record data must specify locations in the shared chunk which conform to this alignment.

	For example, iRequestAlignment of 1 is 2 byte aligned (2^1), 2 is 4 byte aligned (2^2) etc. */

	TInt iRequestAlignment;

	/** Indicates whether this unit is capable of detecting changes in its hardware configuration. */

	TBool iHwConfigNotificationSupport;

	/** Reserved field. */

	TInt iReserved1;

	};

typedef TPckgBuf<TSoundFormatsSupportedV02> TSoundFormatsSupportedV02Buf;

/**

The sound format configuration class. This is used to get and set the current configuration

of the sound device (both for playing and recording).

*/

class TCurrentSoundFormatV02

	{

public:

	/** The audio channel configuration: 1=Mono, 2=Stereo etc. */ 

	TInt iChannels;

	/** The sample rate. @see TSoundRate. */

	TSoundRate iRate;

	/** The encoding format. @see TSoundEncoding. */

	TSoundEncoding iEncoding;

	/** The data format: interleaved, non-interleaved etc. @see TSoundDataFormat. */

	TSoundDataFormat iDataFormat;

	/** Reserved field. */

	TInt iReserved1;

	};

typedef TPckgBuf<TCurrentSoundFormatV02> TCurrentSoundFormatV02Buf;

/**

A flag that can be passed via the 'aFlags' argument of the function RSoundSc::PlayData(). This being

set signifies that this particular play request is the last one of a series (ie EOF) and therefore an underflow is

expected after this request completes.

*/

const TUint KSndFlagLastSample=0x00000001;

/** Reserved settings used with CustomConfig(). */

const TInt KSndCustomConfigMaxReserved=0x0FFFFFFF;

#ifdef _DEBUG

const TInt KSndCustom_ForceHwConfigNotifSupported=0x00;

const TInt KSndCustom_CompleteChangeOfHwConfig=0x01;

const TInt KSndCustom_ForceStartTransferError=0x02;

const TInt KSndCustom_ForceTransferDataError=0x03;

const TInt KSndCustom_ForceTransferTimeout=0x04;

#endif

/** A structure used to assemble arguments for the function RSoundSc::PlayData() and to pass these to the driver. */

struct SRequestPlayDataInfo

	{

	TInt iBufferOffset;

	TInt iLength;

	TUint iFlags;

	};	

#ifndef __KERNEL_MODE__

typedef TPckgBuf<TTimeIntervalMicroSeconds> TTimeIntervalMicroSecondsBuf;

#endif

class RSoundSc : public RBusLogicalChannel

	{

private:	

	enum TRequest

	/**

	 Asynchronous request types

	 */

		{

		EMsgRequestPlayData,

		ERequestNotifyChangeOfHwConfig,

		EMsgRequestMax=3,				// All requests less than this value are handled in the driver DFC thread.

		ERequestRecordData,

		ENumRequests,

		EAllRequests = (1<<ENumRequests)-1

		};

	enum TControl

	/**

	 Synchronous request types

	*/

		{

		EMsgControlSetAudioFormat,

		EMsgControlSetBufChunkCreate,

		EMsgControlSetBufChunkOpen,

		EMsgControlSetVolume,

		EMsgControlPause,

		EMsgControlResume,

		EMsgControlCancelSpecific,

		EMsgControlCustomConfig,

		EControlTimePlayed,

		EControlTimeRecorded,

		EMsgControlMax=10,				// All requests less than this value are handled in the driver DFC thread.

		EControlGetCaps,

		EControlGetAudioFormat,

		EControlGetBufConfig,

		EControlGetVolume,

		EControlBytesTransferred,

		EControlResetBytesTransferred,

		EControlReleaseBuffer

		};

	friend class DSoundScLdd;	

public:

	/**

	Get the version number of sound driver interface.

    @return The sound driver interface version number.

	*/

	inline static TVersion VersionRequired();

#ifndef __KERNEL_MODE__

	/**

	Open a channel on a specified sound device. This driver allows more than one channel to be opened on each device.

	@capability MultimediaDD

	@capability Dependent UserEnvironment Is required when opening a record channel.

	@param aUnit The unit number of the sound device.

	@return KErrNone, if successful; KErrPermissionDenied, if process lacks required capabilities

        	otherwise one of the other system-wide error codes. 

	*/

	inline TInt Open(TInt aUnit=KNullUnit);

	/**

	Get the capabilities of the sound device.

	@param aCapsBuf A packaged object which will be filled with the capabilities of the device.

	@see TSoundFormatsSupportedV02.

	*/

	inline void Caps(TDes8& aCapsBuf);

	/**

  	Get the current audio format configuration.

  	@param aFormatBuf A packaged object which will be filled with the audio configuration settings.

    @see TCurrentSoundFormatV02.

	*/

	inline void AudioFormat(TDes8& aFormatBuf);

	/**

  	Set the current audio format configuration.

  	This can't be changed while the driver is currently playing or recording data.

	@param aFormatBuf A packaged object holding the new audio configuration settings to be used.

  	@return KErrNone if successful;

  			KErrInUse if the playing or recording of data is in progress;

          	KErrNotSupported if any configuration values are invalid;

		  	otherwise one of the other system-wide error codes.

	@see TCurrentSoundFormatV02.

	*/

	inline TInt SetAudioFormat(const TDesC8& aFormatBuf);

 	/**

  	Get the current buffer configuration.

	@param aConfigBuf A packaged TSharedChunkBufConfigBase derived object which will be filled with the buffer

					  configuration settings.

	@see TSharedChunkBufConfigBase.

	*/

 	inline void GetBufferConfig(TDes8& aConfigBuf);

 	/**

  	Set the current buffer configuration - creating a shared chunk.

  	The driver will create a shared chunk according to the buffer specification supplied (and will commit

  	memory to it). This will replace any previous shared chunk created by this driver. A handle to

  	the chunk will then be created for the client thread which will be assigned to the RChunk object supplied

  	by the client.

  	The buffer configuration cannot be changed while the driver is currently playing or recording data.

  	Note that a minimum of three buffers are required when recording: one being loaded with record data by the driver,

  	another also owned by the driver - queued ready for the next transfer and a third owned by the client for processing.

  	Note that for record channels, the buffer size specified effectively determines the size of each record request.

  	Hence, for record channels the buffer size must be a multiple of the minimum request size as specified in the capabilities 

  	class. @see TSoundFormatsSupportedV02. It should also be a multiple of the number of bytes per audio sample (e.g. a multiple 

  	of 4 for 2 channels of 16bit PCM).  

	@param aConfigBuf A packaged TSharedChunkBufConfigBase derived object which must be set with the new buffer configuration

					  settings to be used. Note that this function will ignore any buffer offset information specified by the 

					  caller (i.e. setting the flag KScFlagBufOffsetListInUse has no effect).

	@param aChunk An RChunk object to which the chunk handle will be assigned. 

  	@return KErrNone if successful;

  			KErrInUse if the playing or recording of data is in progress;

          	KErrArgument if any configuration values are invalid;

          	KErrNoMemory if the driver failed to allocate memory for the shared chunk specified;

		  	otherwise one of the other system-wide error codes.

	@see TSharedChunkBufConfigBase.

	*/

 	inline TInt SetBufferChunkCreate(const TDesC8& aConfigBuf,RChunk& aChunk);

 	/**

  	Set the current buffer configuration - using an existing shared chunk.

  	The client supplies an existing shared chunk which is to be used by the driver as the play or record buffer. 

  	Any shared chunk previously created by the driver will be closed by it.

  	The buffer configuration cannot be changed while the driver is currently playing or recording data.

  	See RSoundSc::SetBufferChunkCreate for details on the buffer configuration setting necessary for playback or record.

	@param aConfigBuf A packaged TSharedChunkBufConfigBase derived object which must be set with the buffer configuration

					  settings of the chunk supplied. This must include buffer offset information (i.e. the flag 

					  KScFlagBufOffsetListInUse must be set).

	@param aChunk A handle to the shared chunk which is to be used as the play or record buffer. (This must

				  be a valid handle for the calling thread).

  	@return KErrNone if successful;

  			KErrInUse if the playing or recording of data is in progress;

          	KErrArgument if any configuration values are invalid;

		  	otherwise one of the other system-wide error codes.

	@see TSharedChunkBufConfigBase.

	*/

 	inline TInt SetBufferChunkOpen(const TDesC8& aConfigBuf,RChunk& aChunk);

 	/**

  	Get the current play volume or record level.

	@return The current play volume / record level - a value in the range 0 to 255. The value 255 equates to

	the maximum volume and each value below this equates to a 0.5dB step below it.

	*/

	inline TInt Volume();

	/**

	Set the current play volume or record level. The volume can be altered while the driver is in the process

	of playing or recording data.

	@param aVolume The play volume / record level to be set - a value in the range 0 to 255. The value 255

		equates to the maximum volume and each value below this equates to a 0.5dB step below it.

    @return KErrNone if successful;

          	KErrArgument if the specified volume is out of range;

		  	otherwise one of the other system-wide error codes.

	*/

	inline TInt SetVolume(TInt aVolume);

	/**

	Submit a request to play (write data) to the sound device from a buffer.

  	The buffer must be contained within the driver's shared chunk. A single play request may not span more than one

  	buffer even if two or more buffers are contiguous within the shared chunk.

  	The driver will allow more than one play request to be pending at any time. It will

  	process requests in FIFO order. This is an asynchronous operation with the driver completing the request and

  	returning the request status once all the specified data has been delivered to the sound device. The driver

  	will return a request status of KErrUnderflow each time it completes the last pending play request unless this

  	request was marked with the KSndFlagLastSample flag. If this flag is set, the driver will return

  	KErrNone in this situation. Therefore when it is required to play uninterrupted audio by issuing a series of play

  	requests, the client should mark the last play request using this flag.

	@param aStatus 		 The request status which is signalled when all of the specified data has been transferred to

						 the sound device (or when an error occurs). Possible values:

								KErrNone:	   if all the specified data was successfully transferred and no underflow

											   occured following this transfer (or if an underflow occurred but the

											   request was marked with the KSndFlagLastSample flag);

								KErrUnderflow: if data underflow occurred during or immediately following the transfer;

								otherwise one of the system-wide error codes.

	@param aBufferOffset Offset from the beginning of the shared chunk for the start of data to be played. This must be

						 aligned to a value conforming to the iRequestAlignment member of the capabilities structure.

						 @see TSoundFormatsSupportedV02.

  	@param aLength 		 Number of bytes of data to be played. This must be a multiple of the minimum request size as

  						 specified in the capabilities class. @see TSoundFormatsSupportedV02. It should also be a multiple

  						 of the number of bytes per audio sample (e.g. a multiple of 4 for 2 channels of 16bit PCM).

  	@param aFlags 		 Play request flags. Use KSndFlagLastSample to mark the last play request in a series of play

  						 requests.

	@pre The buffer must have been previously initialised by a call to SetBufferChunkN().

	*/

	inline void PlayData(TRequestStatus& aStatus,TInt aBufferOffset,TInt aLength,TUint aFlags=0);

	/**

	Get the next available record buffer. More than one request may be pending at any time. This is an asynchronous

	operation. If the driver is not already recording then the issuing of this request will start the capturing of

	record data from the sound device into a record buffer.

	@param aStatus	The request status which is signalled when buffer is available (or an error occurs). If

					the request is successful then this result value is set to the offset within the shared chunk

					where the buffer resides. Alternatively, if an error occurs, it will be set to one of

					the system wide error values. These include:

					KErrInUse: if the client needs to free up record buffers;

					KErrOverflow: if it was necessary for the driver to over-write unread record data since the

								  last record request;

					KErrCancel: if the device is paused and there is no un-read record data available.			  

					otherwise one of the system-wide error codes.

  	@param aLength	On return, this contains the number of record bytes successfully stored in the buffer. 

	@pre The record buffer must have been previously initialised by a call to SetBufferChunkN().

	*/

	inline void RecordData(TRequestStatus& aStatus, TInt& aLength);

	/**

	Release a record buffer - making it available again for the driver to record into.

	@param aChunkOffset: The chunk offset of the image to be released. This is the value that was returned by the

						 RecordData() request when the buffer was claimed by the client.

	@return KErrNone: if successful;

			KErrNotFound: if the chunk offset is invalid;

			otherwise one of the system-wide error codes.

	*/

	inline TInt ReleaseBuffer(TInt aChunkOffset);

	/**

	Cancel all outstanding play requests.

	This immediately stops the driver playing data and all outstanding play requests are completed with KErrCancel.

	*/

	inline void CancelPlayData();

	/**

	Cancel all outstanding record requests.

	This immediately stops the driver from capturing record data and all outstanding record requests are completed

	with KErrCancel.

	*/

	inline void CancelRecordData();

	/**

	Cancel a specific record or play request.

	The outstanding request completes with KErrCancel.

	@param aStatus The request status object associated with the request to be cancelled.

	*/			   

	inline void Cancel(const TRequestStatus& aStatus);

	/**

	For a play back units, this method returns the number of bytes delivered to the sound device hardware. For

	recording units, this method returns the number of bytes read from the sound device hardware. This is the

	count since the driver was opened or since the last ResetBytesTransferred() command was issued.	

	@return The number of bytes transferred.

	@see ResetBytesTransferred()

	*/

	inline TInt BytesTransferred();

	/**

	Reset the count of the number of bytes transferred by the sound device..