sl@0: // Copyright (c) 1998-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 the License "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: // e32\include\d32soundsc.h
sl@0: // User side class definition for the shared chunk sound driver.
sl@0: // 
sl@0: //
sl@0: 
sl@0: /**
sl@0:  @file
sl@0:  @publishedPartner
sl@0:  @prototype
sl@0: */
sl@0: 
sl@0: #ifndef __D32SOUNDSC_H__
sl@0: #define __D32SOUNDSC_H__
sl@0: 
sl@0: #include <e32cmn.h>
sl@0: #include <e32ver.h>
sl@0: #ifndef __KERNEL_MODE__
sl@0: #include <e32std.h>
sl@0: #endif
sl@0: 
sl@0: _LIT(KDevSoundScName,"SoundSc");
sl@0: 
sl@0: const TInt KSoundScTxUnit0=0;
sl@0: const TInt KSoundScTxUnit1=1;
sl@0: /**
sl@0: @capability UserEnvironment
sl@0: @ref RSoundSc::Open An RSoundSc may not be opened for record without UserEnvironment
sl@0: */
sl@0: const TInt KSoundScRxUnit0=4;
sl@0: /**
sl@0: @capability UserEnvironment
sl@0: @ref RSoundSc::Open An RSoundSc may not be opened for record without UserEnvironment
sl@0: */
sl@0: const TInt KSoundScRxUnit1=5;
sl@0: 
sl@0: // Note that the implementation in the sound driver LDD to calculate a default audio configuration assumes a 
sl@0: // monotonic ordering of all caps bitfields. If it is necessary to break this ordering then this implementation
sl@0: // will need to be reviewed and possibly changed.
sl@0: 
sl@0: /**
sl@0: Sound driver capability constants - bitmasks of the audio channel configurations supported
sl@0: by a unit. @see TSoundFormatsSupportedV02.
sl@0: */
sl@0: /** The unit supports Mono (i.e. a single audio channel). */
sl@0: const TUint KSoundMonoChannel = 0x0001;
sl@0: /** The unit supports Stereo (i.e. two audio channels). */
sl@0: const TUint KSoundStereoChannel = 0x0002;
sl@0: /** The unit supports three audio channels. */
sl@0: const TUint KSoundThreeChannel = 0x0004;
sl@0: /** The unit supports four audio channels. */
sl@0: const TUint KSoundFourChannel = 0x0008;
sl@0: /** The unit supports five audio channels. */
sl@0: const TUint KSoundFiveChannel = 0x0010;
sl@0: /** The unit supports six audio channels. */
sl@0: const TUint KSoundSixChannel = 0x0020;
sl@0: 
sl@0: /**
sl@0: Sound driver capability constants - bitmasks of supported sample rates. @see TSoundFormatsSupportedV02.
sl@0: */
sl@0: /** The device supports the 7.35KHz sample rate. */
sl@0: const TUint KSoundRate7350Hz = 0x0001;
sl@0: /** The device supports the 8KHz sample rate. */
sl@0: const TUint KSoundRate8000Hz = 0x0002;
sl@0: /** The device supports the 8.82KHz sample rate. */
sl@0: const TUint KSoundRate8820Hz = 0x0004;
sl@0: /** The device supports the 9.6KHz sample rate. */
sl@0: const TUint KSoundRate9600Hz = 0x0008;
sl@0: /** The device supports the 11.025KHz sample rate. */
sl@0: const TUint KSoundRate11025Hz = 0x0010;
sl@0: /** The device supports the 12KHz sample rate. */
sl@0: const TUint KSoundRate12000Hz = 0x0020;
sl@0: /** The device supports the 14.7KHz sample rate. */
sl@0: const TUint KSoundRate14700Hz = 0x0040;
sl@0: /** The device supports the 16KHz sample rate. */
sl@0: const TUint KSoundRate16000Hz = 0x0080;
sl@0: /** The device supports the 22.05KHz sample rate. */
sl@0: const TUint KSoundRate22050Hz = 0x0100;
sl@0: /** The device supports the 24KHz sample rate. */
sl@0: const TUint KSoundRate24000Hz = 0x0200;
sl@0: /** The device supports the 29.4KHz sample rate. */
sl@0: const TUint KSoundRate29400Hz = 0x0400;
sl@0: /** The device supports the 32KHz sample rate. */
sl@0: const TUint KSoundRate32000Hz = 0x0800;
sl@0: /** The device supports the 44.1KHz sample rate. */
sl@0: const TUint KSoundRate44100Hz = 0x1000;
sl@0: /** The device supports the 48KHz sample rate. */
sl@0: const TUint KSoundRate48000Hz = 0x2000;
sl@0: 
sl@0: /**
sl@0: Sound driver capability constants - bitmasks of supported encoding formats. @see TSoundFormatsSupportedV02.
sl@0: */
sl@0: /** The device supports 8bit PCM encoding format. */
sl@0: const TUint KSoundEncoding8BitPCM = 0x0001;
sl@0: /** The device supports 16bit PCM encoding format. */
sl@0: const TUint KSoundEncoding16BitPCM = 0x0002;
sl@0: /** The device supports 24bit PCM encoding format. */
sl@0: const TUint KSoundEncoding24BitPCM = 0x0004;
sl@0: 
sl@0: /**
sl@0: Sound driver capability constants - bitmasks of the data formats supported
sl@0: by the device. @see TSoundFormatsSupportedV02.
sl@0: */
sl@0: /** The device supports an interleaved data format (i.e. data for each channel is interleaved throughout
sl@0: each data buffer). */
sl@0: const TUint KSoundDataFormatInterleaved = 0x0001;
sl@0: /** The device supports a non-interleaved data format (i.e. data for each channel is arranged in
sl@0: contiguous regions within each data buffer). */
sl@0: const TUint KSoundDataFormatNonInterleaved = 0x0002;
sl@0: 
sl@0: /** The maximum setting possible for the record level / volume. */
sl@0: const TInt KSoundMaxVolume = 255;
sl@0: 
sl@0: /**
sl@0: Enumeration of possible data transfer directions. @see TSoundFormatsSupportedV02.
sl@0: */
sl@0: enum TSoundDirection
sl@0: 	{
sl@0: 	/**	A unit for recording data. */
sl@0: 	ESoundDirRecord,
sl@0: 	/** A unit for playing data. */
sl@0: 	ESoundDirPlayback
sl@0: 	};
sl@0: 
sl@0: /**
sl@0: Enumeration of possible sample rates. @see TCurrentSoundFormatV02.
sl@0: */	
sl@0: enum TSoundRate
sl@0: 	{
sl@0: 	/** 7.35KHz sample rate. */
sl@0: 	ESoundRate7350Hz,
sl@0: 	/** 8KHz sample rate. */
sl@0: 	ESoundRate8000Hz,
sl@0: 	/** 8.82KHz sample rate. */
sl@0: 	ESoundRate8820Hz,
sl@0: 	/** 9.6KHz sample rate. */
sl@0: 	ESoundRate9600Hz,
sl@0: 	/** 11.025KHz sample rate. */
sl@0: 	ESoundRate11025Hz,
sl@0: 	/** 12KHz sample rate. */
sl@0: 	ESoundRate12000Hz,
sl@0: 	/** 14.7KHz sample rate. */
sl@0: 	ESoundRate14700Hz,
sl@0: 	/** 16KHz sample rate. */
sl@0: 	ESoundRate16000Hz,
sl@0: 	/** 22.05KHz sample rate. */
sl@0: 	ESoundRate22050Hz,
sl@0: 	/** 24KHz sample rate. */
sl@0: 	ESoundRate24000Hz,
sl@0: 	/** 29.4KHz sample rate. */
sl@0: 	ESoundRate29400Hz,
sl@0: 	/** 32KHz sample rate. */
sl@0: 	ESoundRate32000Hz,
sl@0: 	/** 44.1KHz sample rate. */
sl@0: 	ESoundRate44100Hz,
sl@0: 	/** 48KHz sample rate. */
sl@0: 	ESoundRate48000Hz
sl@0: 	};
sl@0: 
sl@0: /**
sl@0: Enumeration of possible sound encoding formats. @see TCurrentSoundFormatV02.
sl@0: */
sl@0: enum TSoundEncoding
sl@0: 	{
sl@0: 	/** 8bit PCM encoding format. */
sl@0: 	ESoundEncoding8BitPCM,
sl@0: 	/** 16bit PCM encoding format. */
sl@0: 	ESoundEncoding16BitPCM,
sl@0: 	/** 24bit PCM encoding format. */
sl@0: 	ESoundEncoding24BitPCM
sl@0: 	};
sl@0: 	
sl@0: /**
sl@0: Enumeration of possible sound data formats. @see TCurrentSoundFormatV02.
sl@0: */
sl@0: enum TSoundDataFormat
sl@0: 	{
sl@0: 	/** The device supports an interleaved data format. */ 
sl@0: 	ESoundDataFormatInterleaved,
sl@0: 	/** The device supports a non-interleaved data format. */
sl@0: 	ESoundDataFormatNonInterleaved
sl@0: 	};	
sl@0: 	
sl@0: /**
sl@0: The general driver capabilites class - returned by the LDD factory in response to RDevice::GetCaps().
sl@0: */
sl@0: class TCapsSoundScV01
sl@0: 	{
sl@0: public:
sl@0: 	TVersion iVersion;
sl@0: 	};
sl@0: 
sl@0: /**
sl@0: The main audio capabilities class. This is used by the LDD to get either the play or record capabilities
sl@0: of a particular sound device once a channel to it has been opened.
sl@0: */
sl@0: class TSoundFormatsSupportedV02
sl@0: 	{
sl@0: public:
sl@0: 	/** The data transfer direction for this unit: play or record. @see TSoundDirection. */
sl@0: 	TSoundDirection iDirection;
sl@0: 	/** The audio channel configurations supported by this unit - a bitfield. */
sl@0: 	TUint32 iChannels;
sl@0: 	/** The sample rates supported - a bitfield. */
sl@0: 	TUint32 iRates;
sl@0: 	/** The encoding formats supported - a bitfield. */
sl@0: 	TUint32 iEncodings;
sl@0: 	/** The data formats supported - a bitfield. */
sl@0: 	TUint32 iDataFormats;
sl@0: 	/** The minimum request size that the device can support. All requests to play or record data must be of a
sl@0: 	length that is a multiple of this value. */
sl@0: 	TInt iRequestMinSize;
sl@0: 	/** The logarithm to base 2 of the alignment required for request arguments. All requests to play or
sl@0: 	record data must specify locations in the shared chunk which conform to this alignment.
sl@0: 	For example, iRequestAlignment of 1 is 2 byte aligned (2^1), 2 is 4 byte aligned (2^2) etc. */
sl@0: 	TInt iRequestAlignment;
sl@0: 	/** Indicates whether this unit is capable of detecting changes in its hardware configuration. */
sl@0: 	TBool iHwConfigNotificationSupport;
sl@0: 	/** Reserved field. */
sl@0: 	TInt iReserved1;
sl@0: 	};
sl@0: typedef TPckgBuf<TSoundFormatsSupportedV02> TSoundFormatsSupportedV02Buf;
sl@0: 
sl@0: /**
sl@0: The sound format configuration class. This is used to get and set the current configuration
sl@0: of the sound device (both for playing and recording).
sl@0: */
sl@0: class TCurrentSoundFormatV02
sl@0: 	{
sl@0: public:
sl@0: 	/** The audio channel configuration: 1=Mono, 2=Stereo etc. */ 
sl@0: 	TInt iChannels;
sl@0: 	/** The sample rate. @see TSoundRate. */
sl@0: 	TSoundRate iRate;
sl@0: 	/** The encoding format. @see TSoundEncoding. */
sl@0: 	TSoundEncoding iEncoding;
sl@0: 	/** The data format: interleaved, non-interleaved etc. @see TSoundDataFormat. */
sl@0: 	TSoundDataFormat iDataFormat;
sl@0: 	/** Reserved field. */
sl@0: 	TInt iReserved1;
sl@0: 	};
sl@0: typedef TPckgBuf<TCurrentSoundFormatV02> TCurrentSoundFormatV02Buf;
sl@0: 
sl@0: /**
sl@0: A flag that can be passed via the 'aFlags' argument of the function RSoundSc::PlayData(). This being
sl@0: set signifies that this particular play request is the last one of a series (ie EOF) and therefore an underflow is
sl@0: expected after this request completes.
sl@0: */
sl@0: const TUint KSndFlagLastSample=0x00000001;
sl@0: 
sl@0: /** Reserved settings used with CustomConfig(). */
sl@0: const TInt KSndCustomConfigMaxReserved=0x0FFFFFFF;
sl@0: #ifdef _DEBUG
sl@0: const TInt KSndCustom_ForceHwConfigNotifSupported=0x00;
sl@0: const TInt KSndCustom_CompleteChangeOfHwConfig=0x01;
sl@0: const TInt KSndCustom_ForceStartTransferError=0x02;
sl@0: const TInt KSndCustom_ForceTransferDataError=0x03;
sl@0: const TInt KSndCustom_ForceTransferTimeout=0x04;
sl@0: #endif
sl@0: 
sl@0: /** A structure used to assemble arguments for the function RSoundSc::PlayData() and to pass these to the driver. */
sl@0: struct SRequestPlayDataInfo
sl@0: 	{
sl@0: 	TInt iBufferOffset;
sl@0: 	TInt iLength;
sl@0: 	TUint iFlags;
sl@0: 	};	
sl@0: 
sl@0: #ifndef __KERNEL_MODE__
sl@0: typedef TPckgBuf<TTimeIntervalMicroSeconds> TTimeIntervalMicroSecondsBuf;
sl@0: #endif
sl@0: 
sl@0: class RSoundSc : public RBusLogicalChannel
sl@0: 	{
sl@0: private:	
sl@0: 	enum TRequest
sl@0: 	/**
sl@0: 	 Asynchronous request types
sl@0: 	 */
sl@0: 		{
sl@0: 		EMsgRequestPlayData,
sl@0: 		ERequestNotifyChangeOfHwConfig,
sl@0: 		EMsgRequestMax=3,				// All requests less than this value are handled in the driver DFC thread.
sl@0: 		ERequestRecordData,
sl@0: 		ENumRequests,
sl@0: 		EAllRequests = (1<<ENumRequests)-1
sl@0: 		};
sl@0: 		
sl@0: 	enum TControl
sl@0: 	/**
sl@0: 	 Synchronous request types
sl@0: 	*/
sl@0: 		{
sl@0: 		EMsgControlSetAudioFormat,
sl@0: 		EMsgControlSetBufChunkCreate,
sl@0: 		EMsgControlSetBufChunkOpen,
sl@0: 		EMsgControlSetVolume,
sl@0: 		EMsgControlPause,
sl@0: 		EMsgControlResume,
sl@0: 		EMsgControlCancelSpecific,
sl@0: 		EMsgControlCustomConfig,
sl@0: 		EControlTimePlayed,
sl@0: 		EControlTimeRecorded,
sl@0: 		EMsgControlMax=10,				// All requests less than this value are handled in the driver DFC thread.
sl@0: 		EControlGetCaps,
sl@0: 		EControlGetAudioFormat,
sl@0: 		EControlGetBufConfig,
sl@0: 		EControlGetVolume,
sl@0: 		EControlBytesTransferred,
sl@0: 		EControlResetBytesTransferred,
sl@0: 		EControlReleaseBuffer
sl@0: 		};
sl@0: 	friend class DSoundScLdd;	
sl@0: public:
sl@0: 	/**
sl@0: 	Get the version number of sound driver interface.
sl@0:     @return The sound driver interface version number.
sl@0: 	*/
sl@0: 	inline static TVersion VersionRequired();
sl@0: 
sl@0: #ifndef __KERNEL_MODE__
sl@0: 	/**
sl@0: 	Open a channel on a specified sound device. This driver allows more than one channel to be opened on each device.
sl@0: 	@capability MultimediaDD
sl@0: 	@capability Dependent UserEnvironment Is required when opening a record channel.
sl@0: 	@param aUnit The unit number of the sound device.
sl@0: 	@return KErrNone, if successful; KErrPermissionDenied, if process lacks required capabilities
sl@0:         	otherwise one of the other system-wide error codes. 
sl@0: 	*/
sl@0: 	inline TInt Open(TInt aUnit=KNullUnit);
sl@0: 	
sl@0: 	/**
sl@0: 	Get the capabilities of the sound device.
sl@0: 	@param aCapsBuf A packaged object which will be filled with the capabilities of the device.
sl@0: 	@see TSoundFormatsSupportedV02.
sl@0: 	*/
sl@0: 	inline void Caps(TDes8& aCapsBuf);
sl@0: 	
sl@0: 	/**
sl@0:   	Get the current audio format configuration.
sl@0:   	@param aFormatBuf A packaged object which will be filled with the audio configuration settings.
sl@0:     @see TCurrentSoundFormatV02.
sl@0: 	*/
sl@0: 	inline void AudioFormat(TDes8& aFormatBuf);
sl@0: 	
sl@0: 	/**
sl@0:   	Set the current audio format configuration.
sl@0:   	This can't be changed while the driver is currently playing or recording data.
sl@0: 	@param aFormatBuf A packaged object holding the new audio configuration settings to be used.
sl@0:   	@return KErrNone if successful;
sl@0:   			KErrInUse if the playing or recording of data is in progress;
sl@0:           	KErrNotSupported if any configuration values are invalid;
sl@0: 		  	otherwise one of the other system-wide error codes.
sl@0: 	@see TCurrentSoundFormatV02.
sl@0: 	*/
sl@0: 	inline TInt SetAudioFormat(const TDesC8& aFormatBuf);
sl@0: 	
sl@0:  	/**
sl@0:   	Get the current buffer configuration.
sl@0: 	@param aConfigBuf A packaged TSharedChunkBufConfigBase derived object which will be filled with the buffer
sl@0: 					  configuration settings.
sl@0: 	@see TSharedChunkBufConfigBase.
sl@0: 	*/
sl@0:  	inline void GetBufferConfig(TDes8& aConfigBuf);
sl@0:  	
sl@0:  	/**
sl@0:   	Set the current buffer configuration - creating a shared chunk.
sl@0:   	The driver will create a shared chunk according to the buffer specification supplied (and will commit
sl@0:   	memory to it). This will replace any previous shared chunk created by this driver. A handle to
sl@0:   	the chunk will then be created for the client thread which will be assigned to the RChunk object supplied
sl@0:   	by the client.
sl@0:   	The buffer configuration cannot be changed while the driver is currently playing or recording data.
sl@0:   	Note that a minimum of three buffers are required when recording: one being loaded with record data by the driver,
sl@0:   	another also owned by the driver - queued ready for the next transfer and a third owned by the client for processing.
sl@0:   	Note that for record channels, the buffer size specified effectively determines the size of each record request.
sl@0:   	Hence, for record channels the buffer size must be a multiple of the minimum request size as specified in the capabilities 
sl@0:   	class. @see TSoundFormatsSupportedV02. It should also be a multiple of the number of bytes per audio sample (e.g. a multiple 
sl@0:   	of 4 for 2 channels of 16bit PCM).  
sl@0: 	@param aConfigBuf A packaged TSharedChunkBufConfigBase derived object which must be set with the new buffer configuration
sl@0: 					  settings to be used. Note that this function will ignore any buffer offset information specified by the 
sl@0: 					  caller (i.e. setting the flag KScFlagBufOffsetListInUse has no effect).
sl@0: 	@param aChunk An RChunk object to which the chunk handle will be assigned. 
sl@0:   	@return KErrNone if successful;
sl@0:   			KErrInUse if the playing or recording of data is in progress;
sl@0:           	KErrArgument if any configuration values are invalid;
sl@0:           	KErrNoMemory if the driver failed to allocate memory for the shared chunk specified;
sl@0: 		  	otherwise one of the other system-wide error codes.
sl@0: 	@see TSharedChunkBufConfigBase.
sl@0: 	*/
sl@0:  	inline TInt SetBufferChunkCreate(const TDesC8& aConfigBuf,RChunk& aChunk);
sl@0:  	
sl@0:  	/**
sl@0:   	Set the current buffer configuration - using an existing shared chunk.
sl@0:   	The client supplies an existing shared chunk which is to be used by the driver as the play or record buffer. 
sl@0:   	Any shared chunk previously created by the driver will be closed by it.
sl@0:   	The buffer configuration cannot be changed while the driver is currently playing or recording data.
sl@0:   	See RSoundSc::SetBufferChunkCreate for details on the buffer configuration setting necessary for playback or record.
sl@0: 	@param aConfigBuf A packaged TSharedChunkBufConfigBase derived object which must be set with the buffer configuration
sl@0: 					  settings of the chunk supplied. This must include buffer offset information (i.e. the flag 
sl@0: 					  KScFlagBufOffsetListInUse must be set).
sl@0: 	@param aChunk A handle to the shared chunk which is to be used as the play or record buffer. (This must
sl@0: 				  be a valid handle for the calling thread).
sl@0:   	@return KErrNone if successful;
sl@0:   			KErrInUse if the playing or recording of data is in progress;
sl@0:           	KErrArgument if any configuration values are invalid;
sl@0: 		  	otherwise one of the other system-wide error codes.
sl@0: 	@see TSharedChunkBufConfigBase.
sl@0: 	*/
sl@0:  	inline TInt SetBufferChunkOpen(const TDesC8& aConfigBuf,RChunk& aChunk);
sl@0:  	
sl@0:  	/**
sl@0:   	Get the current play volume or record level.
sl@0: 	@return The current play volume / record level - a value in the range 0 to 255. The value 255 equates to
sl@0: 	the maximum volume and each value below this equates to a 0.5dB step below it.
sl@0: 	*/
sl@0: 	inline TInt Volume();
sl@0: 	
sl@0: 	/**
sl@0: 	Set the current play volume or record level. The volume can be altered while the driver is in the process
sl@0: 	of playing or recording data.
sl@0: 	@param aVolume The play volume / record level to be set - a value in the range 0 to 255. The value 255
sl@0: 		equates to the maximum volume and each value below this equates to a 0.5dB step below it.
sl@0:     @return KErrNone if successful;
sl@0:           	KErrArgument if the specified volume is out of range;
sl@0: 		  	otherwise one of the other system-wide error codes.
sl@0: 	*/
sl@0: 	inline TInt SetVolume(TInt aVolume);
sl@0: 	
sl@0: 	/**
sl@0: 	Submit a request to play (write data) to the sound device from a buffer.
sl@0:   	The buffer must be contained within the driver's shared chunk. A single play request may not span more than one
sl@0:   	buffer even if two or more buffers are contiguous within the shared chunk.
sl@0:   	The driver will allow more than one play request to be pending at any time. It will
sl@0:   	process requests in FIFO order. This is an asynchronous operation with the driver completing the request and
sl@0:   	returning the request status once all the specified data has been delivered to the sound device. The driver
sl@0:   	will return a request status of KErrUnderflow each time it completes the last pending play request unless this
sl@0:   	request was marked with the KSndFlagLastSample flag. If this flag is set, the driver will return
sl@0:   	KErrNone in this situation. Therefore when it is required to play uninterrupted audio by issuing a series of play
sl@0:   	requests, the client should mark the last play request using this flag.
sl@0: 	@param aStatus 		 The request status which is signalled when all of the specified data has been transferred to
sl@0: 						 the sound device (or when an error occurs). Possible values:
sl@0: 								KErrNone:	   if all the specified data was successfully transferred and no underflow
sl@0: 											   occured following this transfer (or if an underflow occurred but the
sl@0: 											   request was marked with the KSndFlagLastSample flag);
sl@0: 								KErrUnderflow: if data underflow occurred during or immediately following the transfer;
sl@0: 								otherwise one of the system-wide error codes.
sl@0: 	@param aBufferOffset Offset from the beginning of the shared chunk for the start of data to be played. This must be
sl@0: 						 aligned to a value conforming to the iRequestAlignment member of the capabilities structure.
sl@0: 						 @see TSoundFormatsSupportedV02.
sl@0:   	@param aLength 		 Number of bytes of data to be played. This must be a multiple of the minimum request size as
sl@0:   						 specified in the capabilities class. @see TSoundFormatsSupportedV02. It should also be a multiple
sl@0:   						 of the number of bytes per audio sample (e.g. a multiple of 4 for 2 channels of 16bit PCM).
sl@0:   	@param aFlags 		 Play request flags. Use KSndFlagLastSample to mark the last play request in a series of play
sl@0:   						 requests.
sl@0: 	@pre The buffer must have been previously initialised by a call to SetBufferChunkN().
sl@0: 	*/
sl@0: 	inline void PlayData(TRequestStatus& aStatus,TInt aBufferOffset,TInt aLength,TUint aFlags=0);
sl@0: 	
sl@0: 	/**
sl@0: 	Get the next available record buffer. More than one request may be pending at any time. This is an asynchronous
sl@0: 	operation. If the driver is not already recording then the issuing of this request will start the capturing of
sl@0: 	record data from the sound device into a record buffer.
sl@0: 	@param aStatus	The request status which is signalled when buffer is available (or an error occurs). If
sl@0: 					the request is successful then this result value is set to the offset within the shared chunk
sl@0: 					where the buffer resides. Alternatively, if an error occurs, it will be set to one of
sl@0: 					the system wide error values. These include:
sl@0: 					KErrInUse: if the client needs to free up record buffers;
sl@0: 					KErrOverflow: if it was necessary for the driver to over-write unread record data since the
sl@0: 								  last record request;
sl@0: 					KErrCancel: if the device is paused and there is no un-read record data available.			  
sl@0: 					otherwise one of the system-wide error codes.
sl@0:   	@param aLength	On return, this contains the number of record bytes successfully stored in the buffer. 
sl@0: 	@pre The record buffer must have been previously initialised by a call to SetBufferChunkN().
sl@0: 	*/
sl@0: 	inline void RecordData(TRequestStatus& aStatus, TInt& aLength);
sl@0: 	
sl@0: 	/**
sl@0: 	Release a record buffer - making it available again for the driver to record into.
sl@0: 	@param aChunkOffset: The chunk offset of the image to be released. This is the value that was returned by the
sl@0: 						 RecordData() request when the buffer was claimed by the client.
sl@0: 	@return KErrNone: if successful;
sl@0: 			KErrNotFound: if the chunk offset is invalid;
sl@0: 			otherwise one of the system-wide error codes.
sl@0: 	*/
sl@0: 	inline TInt ReleaseBuffer(TInt aChunkOffset);
sl@0: 	
sl@0: 	/**
sl@0: 	Cancel all outstanding play requests.
sl@0: 	This immediately stops the driver playing data and all outstanding play requests are completed with KErrCancel.
sl@0: 	*/
sl@0: 	inline void CancelPlayData();
sl@0: 	
sl@0: 	/**
sl@0: 	Cancel all outstanding record requests.
sl@0: 	This immediately stops the driver from capturing record data and all outstanding record requests are completed
sl@0: 	with KErrCancel.
sl@0: 	*/
sl@0: 	inline void CancelRecordData();
sl@0: 	
sl@0: 	/**
sl@0: 	Cancel a specific record or play request.
sl@0: 	The outstanding request completes with KErrCancel.
sl@0: 	@param aStatus The request status object associated with the request to be cancelled.
sl@0: 	*/			   
sl@0: 	inline void Cancel(const TRequestStatus& aStatus);
sl@0: 	
sl@0: 	/**
sl@0: 	For a play back units, this method returns the number of bytes delivered to the sound device hardware. For
sl@0: 	recording units, this method returns the number of bytes read from the sound device hardware. This is the
sl@0: 	count since the driver was opened or since the last ResetBytesTransferred() command was issued.	
sl@0: 	@return The number of bytes transferred.
sl@0: 	@see ResetBytesTransferred()
sl@0: 	*/
sl@0: 	inline TInt BytesTransferred();
sl@0: 	
sl@0: 	/**
sl@0: 	Reset the count of the number of bytes transferred by the sound device..
sl@0: 	@see BytesTransferred().
sl@0: 	*/
sl@0: 	inline void ResetBytesTransferred();
sl@0: 	
sl@0: 	/**
sl@0: 	Halt the playing or recording of data from the sound device.
sl@0: 	Playing or recording can be resumed using Resume().
sl@0: 	If an incomplete play request is outstanding when the device is paused, this request does not complete as a 
sl@0: 	result. Resuming play operation following a pause will cause the driver to re-commence playing data from the 
sl@0: 	next sample following the last one played - even of this is part way through a play buffer.
sl@0: 	However, if an incomplete record request is outstanding when recording is paused, this will be completed immediately
sl@0: 	as a result. Typically this will be a partially filled record buffer and the number of valid bytes in the buffer are
sl@0: 	indicated via the length argument of the RecordData() method. The client should release this buffer in the normal
sl@0: 	way in order to make it available again to the driver when recoding is resumed. Any other outstanding record
sl@0: 	requests are completed immediately when recording is halted with a return value of KErrCancel. Likewise, record 
sl@0: 	requests received after the device has been paused will complete immediately in the same way - either successfully
sl@0: 	if un-read data is available or KErrCancel if not. The device must be resumed before it can be primed to capture a
sl@0: 	new record buffer. The driver will capture no record data while it is in the paused state. If recording is resumed,
sl@0: 	the driver will begin storing the received data from the beginning of its next available record buffer.
sl@0: 	@return KErrNone if successful;
sl@0:   			KErrNotReady: if the driver is not currently playing or recording;
sl@0: 		  	otherwise one of the other system-wide error codes.
sl@0: 	@see Resume()
sl@0: 	*/
sl@0: 	inline TInt Pause();
sl@0: 	
sl@0: 	/**
sl@0: 	Allow the sound device to resume playing or recording data.
sl@0: 	This is used resume the operation of the driver following a earlier Pause() command to pause play or record.
sl@0: 	@return KErrNone if successful;
sl@0:   			KErrNotReady: if the driver is not currently paused;
sl@0: 		  	otherwise one of the other system-wide error codes.
sl@0: 	@see Pause()
sl@0: 	*/
sl@0: 	inline TInt Resume();
sl@0: 	
sl@0: 	/**
sl@0: 	Register for notification of a change in the hardware configuration of the device.
sl@0: 	This is an asynchronous operation. Only one request of this type can be outstanding per driver channel.
sl@0: 	@param aStatus The request status which is signalled when a change in hardware configuration occurs. Possible
sl@0: 		values returned:
sl@0: 			KErrNotSupported: The unit cannot detect changes in configuration;
sl@0: 			KErrInUse: A notification request is already outstanding for this driver channel.
sl@0: 			KErrNone: A normal change in hardware configuration has occured;
sl@0: 			otherwise one of the other system-wide error codes.
sl@0: 	@param aHeadsetPresent On return, this is set to ETrue if the unit is connected to a microphone or headset socket and
sl@0: 		this is now present. Otherwise it returns EFalse.
sl@0: 	*/
sl@0: 	inline void NotifyChangeOfHwConfig(TRequestStatus& aStatus,TBool& aHeadsetPresent);
sl@0: 
sl@0: 	/**
sl@0: 	Cancel a request for notification of a change in the hardware configuration.
sl@0: 	This results in a pending request being completed immediately with KErrCancel.
sl@0: 	*/
sl@0: 	inline void CancelNotifyChangeOfHwConfig();
sl@0: 	
sl@0: 	/**
sl@0: 	Issue a custom configuration request.
sl@0: 	@param aFunction A number identifying the request. (Values below 0x10000000 are reserved).
sl@0: 	@param aParam A 32-bit value passed to the driver. Its meaning depends on the request.
sl@0: 	@return KErrNone if successful, otherwise one of the other system wide error codes.
sl@0: 	*/
sl@0: 	inline TInt CustomConfig(TInt aFunction,TAny* aParam=NULL);
sl@0: 
sl@0: 	/**
sl@0: 	Calculates and returns the number of microseconds of data played since the start of playback.  If playback ends or
sl@0: 	if CancelPlayData() is called, this number will be reset.
sl@0: 	@param aTimePlayed A packaged TTimeIntervalMicroSecondsBuf into which to place the number of microseconds played.
sl@0: 	@return	KErrNone if successful.
sl@0: 			KErrNotSupported if unit is not open for playback.
sl@0: 			Otherwise one of the other system wide error codes.
sl@0: 	*/
sl@0: 	inline TInt TimePlayed(TTimeIntervalMicroSecondsBuf& aTimePlayed);
sl@0: 
sl@0: 	/**
sl@0: 	Calculates and returns the number of microseconds of data recorded since the start of record.  If recording ends or
sl@0: 	if CancelRecord() is called, this number will be reset.
sl@0: 	@param aTimeRecorded A packaged TTimeIntervalMicroSecondsBuf into which to place the number of microseconds played.
sl@0: 	@return	KErrNone if successful.
sl@0: 			KErrNotSupported if unit is not open for recording.
sl@0: 			Otherwise one of the other system wide error codes.
sl@0: 	*/
sl@0: 	inline TInt TimeRecorded(TTimeIntervalMicroSecondsBuf& aTimeRecorded);
sl@0: 
sl@0: #endif	// __KERNEL_MODE__
sl@0: 	};
sl@0: 
sl@0: #include <d32soundsc.inl>
sl@0: 
sl@0: #endif // __D32SOUNDSC_H__
sl@0: