williamr@2: // Copyright (c) 2001-2009 Nokia Corporation and/or its subsidiary(-ies). williamr@2: // All rights reserved. williamr@2: // This component and the accompanying materials are made available williamr@2: // under the terms of the License "Symbian Foundation License v1.0" to Symbian Foundation members and "Symbian Foundation End User License Agreement v1.0" to non-members williamr@2: // which accompanies this distribution, and is available williamr@2: // at the URL "http://www.symbianfoundation.org/legal/licencesv10.html". williamr@2: // williamr@2: // Initial Contributors: williamr@2: // Nokia Corporation - initial contribution. williamr@2: // williamr@2: // Contributors: williamr@2: // williamr@2: // Description: williamr@2: // williamr@2: williamr@2: #ifndef __SOUNDDEVICE_H__ williamr@2: #define __SOUNDDEVICE_H__ williamr@2: williamr@2: #include williamr@2: #include williamr@2: #include williamr@2: #include williamr@2: #include williamr@2: williamr@2: williamr@2: //Debugging info williamr@2: williamr@2: /* williamr@2: Notes: williamr@2: This file defines the DevSound class which acts as an interface to williamr@2: the hardware and is intended to invoke VCR functionality via the plug-ins. williamr@2: The DevSound also contains a product specific policy. williamr@2: */ williamr@2: williamr@2: //UIDs for buffers: According to Symbian: Not used williamr@2: williamr@2: // Public Media Server includes williamr@2: williamr@2: /** williamr@2: @publishedAll williamr@2: @released williamr@2: williamr@2: Sampling rates available. williamr@2: williamr@2: When queried from DevSound by calling the function Capabilities(), iRate indicates williamr@2: the sampling rates supported by the audio device. williamr@2: williamr@2: DevSound by default is configured to 8KHz sampling rate. williamr@2: So to configure DevSound to play/record audio at 16 KHz sampling rate: williamr@2: williamr@2: The mode should not be OR'ed with each other, only single values are accepted. williamr@2: */ williamr@2: enum TMMFSampleRate williamr@2: { williamr@2: /** 8000 Hz Sampling Rate williamr@2: */ williamr@2: EMMFSampleRate8000Hz = 0x00000001, williamr@2: /** 11025 Hz Sampling Rate williamr@2: */ williamr@2: EMMFSampleRate11025Hz = 0x00000002, williamr@2: /** 16000 Hz Sampling Rate williamr@2: */ williamr@2: EMMFSampleRate16000Hz = 0x00000004, williamr@2: /** 22050 Hz Sampling Rate williamr@2: */ williamr@2: EMMFSampleRate22050Hz = 0x00000008, williamr@2: /** 32000 Hz Sampling Rate williamr@2: */ williamr@2: EMMFSampleRate32000Hz = 0x00000010, williamr@2: /** 44100 Hz Sampling Rate williamr@2: */ williamr@2: EMMFSampleRate44100Hz = 0x00000020, williamr@2: /** 48000 Hz Sampling Rate williamr@2: */ williamr@2: EMMFSampleRate48000Hz = 0x00000040, williamr@2: /** 88200 Hz Sampling Rate williamr@2: */ williamr@2: EMMFSampleRate88200Hz = 0x00000080, williamr@2: /** 96000 Hz Sampling Rate williamr@2: */ williamr@2: EMMFSampleRate96000Hz = 0x00000100, williamr@2: /** 12000 Hz Sampling Rate williamr@2: */ williamr@2: EMMFSampleRate12000Hz = 0x00000200, williamr@2: /** 24000 Hz Sampling Rate williamr@2: */ williamr@2: EMMFSampleRate24000Hz = 0x00000400, williamr@2: /** 64000 Hz Sampling Rate williamr@2: */ williamr@2: EMMFSampleRate64000Hz = 0x00000800 williamr@2: }; williamr@2: williamr@2: /** williamr@2: @publishedAll williamr@2: @released williamr@2: williamr@2: Mono Stereo playback and record modes available. williamr@2: williamr@2: When queried from DevSound by calling the function Capabilities(), iChannels williamr@2: indicates whether the underlying audio device supports playing back stereo williamr@2: audio samples and recording audio samples in stereo mode or not. williamr@2: williamr@2: DevSound by default is configured to Mono mode. williamr@2: So to configure DevSound to play/record audio sample in stereo mode: williamr@2: williamr@2: The mode should not be OR'ed with each other, only single values are accepted. williamr@2: */ williamr@2: enum TMMFMonoStereo williamr@2: { williamr@2: /** Mono mode williamr@2: */ williamr@2: EMMFMono = 0x00000001, williamr@2: /** Stereo mode williamr@2: */ williamr@2: EMMFStereo = 0x00000002 williamr@2: }; williamr@2: williamr@2: /** williamr@2: @publishedAll williamr@2: @released williamr@2: williamr@2: Encoding modes available. williamr@2: williamr@2: When queried from DevSound by calling the function Capabilities(), iEncoding williamr@2: provides information about different encoding supported by audio device. williamr@2: williamr@2: DevSound by default is configured to play PCM16 Bit audio data. williamr@2: Setting encoding mode is not supported yet: williamr@2: */ williamr@2: enum TMMFSoundEncoding williamr@2: { williamr@2: /** Signed 8 Bit PCM williamr@2: */ williamr@2: EMMFSoundEncoding8BitPCM = 0x00000001, williamr@2: /** Signed 16 Bit PCM williamr@2: */ williamr@2: EMMFSoundEncoding16BitPCM = 0x00000002, williamr@2: /** Signed 8 Bit ALaw williamr@2: */ williamr@2: EMMFSoundEncoding8BitALaw = 0x00000004, williamr@2: /** Signed 8 Bit MuLaw williamr@2: */ williamr@2: EMMFSoundEncoding8BitMuLaw = 0x00000008, williamr@2: }; williamr@2: williamr@2: /** williamr@2: @publishedAll williamr@2: @released williamr@2: williamr@2: Stereo support enum. williamr@2: */ williamr@2: enum TMMFStereoSupport williamr@2: { williamr@2: /** No stereo support williamr@2: */ williamr@2: EMMFNone = 0x00000000, williamr@2: /** Interleaved stereo support williamr@2: */ williamr@2: EMMFInterleavedOnly = 0x00000001, williamr@2: /** Non Interleaved stereo support williamr@2: */ williamr@2: EMMFNonInterleavedOnly = 0x00000002, williamr@2: /** Interleaved and Non Interleaved stereo support williamr@2: */ williamr@2: EMMFBothNonAndInterleaved = 0x00000003, williamr@2: /** Joint stereo support williamr@2: */ williamr@2: EMMFJoint = 0x00000004 williamr@2: }; williamr@2: williamr@2: /** williamr@2: @publishedAll williamr@2: @released williamr@2: williamr@2: Type class for DevSound implementation device capabilities. williamr@2: williamr@2: CMMFDevSound will return Sampling Rates, Encoding and Stereo feature williamr@2: supported in this structure when queried for capabilities. DevSound can williamr@2: also be configured by setting parameters in this structure and passing the williamr@2: structure to it. williamr@2: */ williamr@2: class TMMFCapabilities williamr@2: { williamr@2: public: williamr@2: /** Sampling Rates supported williamr@2: */ williamr@2: TUint iRate; williamr@2: /** Encodings supported williamr@2: */ williamr@2: TUint iEncoding; williamr@2: /** Mono/Stereo support williamr@2: */ williamr@2: TUint iChannels; williamr@2: /** Buffer size supported williamr@2: */ williamr@2: TInt iBufferSize; williamr@2: }; williamr@2: williamr@2: /** williamr@2: @publishedAll williamr@2: @released williamr@2: williamr@2: An interface to a set of DevSound callback functions. williamr@2: williamr@2: williamr@2: This serves as the method of communication between the client and the williamr@2: DevSound. williamr@2: williamr@2: The class is a mixin and is intended to be inherited by the client class williamr@2: that is interested in observing the DevSound operation. The functions williamr@2: encapsulated by this class are called when specific events occur in the williamr@2: process of initializing and playing/recording an audio sample or playing williamr@2: tones. williamr@2: */ williamr@2: class MDevSoundObserver williamr@2: { williamr@2: public: williamr@2: /** williamr@2: Handles initialization completion event. williamr@2: williamr@2: A derived class must provide an implementation to handle the initialization williamr@2: request. williamr@2: williamr@2: CMMFDevSound object calls this function when its InitializeL() function williamr@2: completes. williamr@2: williamr@2: @param aError williamr@2: Error code. KErrNone if successful. Other values are possible williamr@2: indicating a problem initializing CMMFDevSound object. williamr@2: */ williamr@2: virtual void InitializeComplete(TInt aError)=0; williamr@2: williamr@2: /** williamr@2: Handles tone play completion event. williamr@2: williamr@2: A derived class must provide an implementation to handle the tone play williamr@2: completion request. williamr@2: williamr@2: CMMFDevSound object calls this function when an attempt to play tone has williamr@2: completed, successfully or otherwise. williamr@2: williamr@2: The following are the play tone functions; PlayToneL(), PlayDMTFStringL(), williamr@2: PlayToneSequenceL(), and PlayFixedSequenceL(). williamr@2: williamr@2: @param aError williamr@2: Error code. The status of tone playback. KErrUnderflow playing of williamr@2: the tone is complete. KErrAccessDenied the sound device is in use by williamr@2: another higher priority client. KErrCancel playing of the audio williamr@2: sample is stopped by DevSound client another higher priority client. williamr@2: */ williamr@2: virtual void ToneFinished(TInt aError)=0; williamr@2: williamr@2: /** williamr@2: Handles CMMFDevSound object's data request event. williamr@2: williamr@2: A derived class must provide an implementation to supply CMMFDevSound williamr@2: object the data that it needs to play or convert. williamr@2: williamr@2: CMMFDevSound object calls this function when and where it needs data for williamr@2: playing or converting. The observer should notify CMMFDevSound object as williamr@2: quickly as possible after the data is read into buffer, aBuffer by calling williamr@2: PlayData(), otherwise the implementation might callback function PlayError() williamr@2: on derived class object with error code KErrUnderflow. williamr@2: This does not apply to the very first call to PlayData(), however. williamr@2: It is possible for a user of DevSound to hold the first buffer sent in williamr@2: BufferToBeFilled() until ready to play. williamr@2: The use case for this is if a low latency audio response williamr@2: is required, as at this point all the resources used to play audio are open. williamr@2: If used in this way then it is important to be aware that when when the williamr@2: resources for audio are ready at the BufferToBeFilled() callback, a Devsound williamr@2: on a real device will be running at increased power consumption as the audio williamr@2: hw and any required DSPs will be powered up etc. williamr@2: williamr@2: @param aBuffer williamr@2: Buffer into which data should be read. The amount of data that is williamr@2: needed is specified in CMMFBuffer::RequestSize(). williamr@2: */ williamr@2: virtual void BufferToBeFilled(CMMFBuffer* aBuffer)=0; williamr@2: williamr@2: /** williamr@2: Handles play completion or cancel event. williamr@2: williamr@2: A derived class must provide an implementation to handle the play williamr@2: completion or cancel request. williamr@2: williamr@2: CMMFDevSound object calls this function when an attempt to play audio sample williamr@2: has completed, successfully or otherwise. williamr@2: williamr@2: @param aError williamr@2: Error code. The status of playback. KErrUnderflow playing of the williamr@2: audio sample is complete. KErrAccessDenied the sound device is in williamr@2: use by another higher priority client. williamr@2: */ williamr@2: virtual void PlayError(TInt aError)=0; williamr@2: williamr@2: /** williamr@2: Handles CMMFDevSound object's data request event. williamr@2: williamr@2: A derived class must provide an implementation to process the data williamr@2: supplied by CMMFDevSound object while recording or converting. williamr@2: williamr@2: CMMFDevSound object calls this function when the buffer, aBuffer gets filled williamr@2: while recording or converting. The observer should notify CMMFDevSound williamr@2: object as quickly as possible after data in the buffer is processed by williamr@2: calling RecordData(), otherwise the implementation might callback williamr@2: the function RecordError() on derived class object with error code KErrOverflow. williamr@2: williamr@2: @param aBuffer williamr@2: Buffer containing processed (recorded or converted) data. The amount williamr@2: of data that is available is specified in CMMFBuffer::RequestSize(). williamr@2: */ williamr@2: virtual void BufferToBeEmptied(CMMFBuffer* aBuffer)=0; williamr@2: williamr@2: /** williamr@2: Handles record completion or cancel event. williamr@2: williamr@2: A derived class must provide an implementation to handle the record williamr@2: completion or cancel request. williamr@2: williamr@2: CMMFDevSound object calls this function when an attempt to record audio sample williamr@2: has completed, successfully or otherwise. williamr@2: williamr@2: @param aError williamr@2: Error code. The status of recording. KErrOverflow audio devices williamr@2: runs out of internal buffer. KErrAccessDenied the sound device is williamr@2: in use by another higher priority client. williamr@2: */ williamr@2: virtual void RecordError(TInt aError)=0; williamr@2: williamr@2: /** williamr@2: Handles conversion completion or cancel event. williamr@2: williamr@2: A derived class must provide an implementation to handle the conversion williamr@2: completion or cancel request. williamr@2: williamr@2: CMMFDevSound object calls this function when an attempt to convert data from williamr@2: source format to destination format has completed, successfully or otherwise. williamr@2: williamr@2: @param aError williamr@2: Error code. KErrCancel conversion operation is cancelled. KErrNone williamr@2: conversion is complete. Other values are possible indicating a williamr@2: problem converting data. williamr@2: */ williamr@2: virtual void ConvertError(TInt aError)=0; williamr@2: williamr@2: /** williamr@2: Handles device event. williamr@2: williamr@2: A derived class must provide an implementtion to handle the messages from williamr@2: audio hardware device. williamr@2: williamr@2: CMMFDevSound object calls this function when a message is received from the williamr@2: audio hardware device. williamr@2: williamr@2: @param aMessageType williamr@2: Defines the type of message. Used to determine how to williamr@2: interpret the contents of aMsg. williamr@2: @param aMsg williamr@2: Message that is packed in the Descriptor format. williamr@2: */ williamr@2: virtual void DeviceMessage(TUid aMessageType, const TDesC8& aMsg)=0; williamr@2: williamr@2: williamr@2: /** williamr@2: Handles policy request completion event. williamr@2: williamr@2: A derived class must provide an implementation to handle the policy request williamr@2: completion event. williamr@2: williamr@2: CMMFDevSound object calls this function when an attempt to acquire sound williamr@2: device is rejected by audio policy server. williamr@2: williamr@2: @param aEvent williamr@2: Not used williamr@2: */ williamr@2: inline virtual void SendEventToClient(const TMMFEvent& aEvent); williamr@2: williamr@2: }; williamr@2: williamr@2: williamr@2: /** williamr@2: @publishedAll williamr@2: @released williamr@2: williamr@2: This is the interface from Symbian OS to the raw audio functions on the williamr@2: device hardware. williamr@2: williamr@2: DevSound is currently loaded as a DLL, and implements the VCR-type williamr@2: functions to be expected for such an interface. williamr@2: williamr@2: The audio functions include the following functionality: williamr@2: - Initialisation and configuration of hardware devices, for example, setting microphone gain, williamr@2: setting setero balance and so on. williamr@2: - The playing and recording of raw audio data. williamr@2: - The playing and dynamic control of tones with user specified frequencies. williamr@2: - The playing of DTMF strings. williamr@2: */ williamr@2: class CMMFDevSound : public CBase williamr@2: { williamr@2: public: williamr@2: williamr@2: /** williamr@2: Constructs, and returns a pointer to, a new CMMFDevSound object. williamr@2: williamr@2: Leaves on failure. williamr@2: */ williamr@2: IMPORT_C static CMMFDevSound* NewL(); williamr@2: williamr@2: /** williamr@2: Destructor. williamr@2: williamr@2: Deletes all objects and releases all resource owned by this williamr@2: instance. williamr@2: */ williamr@2: IMPORT_C ~CMMFDevSound(); williamr@2: williamr@2: /** williamr@2: Initializes CMMFDevSound object to play and record PCM16 raw audio data williamr@2: with sampling rate of 8 KHz. williamr@2: williamr@2: On completion of Initialization, calls InitializeComplete() on williamr@2: aDevSoundObserver. williamr@2: williamr@2: Leaves on failure. williamr@2: williamr@2: @param aDevSoundObserver williamr@2: A reference to DevSound Observer instance. williamr@2: @param aMode williamr@2: The mode for which this object will be used. Any value other than EMMFStatePlaying, EMMFStateRecording or EMMFStateTonePlaying is unsupported. williamr@2: williamr@2: williamr@2: */ williamr@2: IMPORT_C void InitializeL(MDevSoundObserver& aDevSoundObserver, TMMFState aMode); williamr@2: williamr@2: williamr@2: /** williamr@2: Initializes DevSound object for the mode aMode for processing audio data williamr@2: with hardware device aHWDev. williamr@2: williamr@2: On completion of Initialization, the observer will be notified via call back williamr@2: InitializeComplete(). williamr@2: williamr@2: Leaves on failure. williamr@2: williamr@2: @param aDevSoundObserver williamr@2: A reference to DevSound Observer instance. williamr@2: @param aHWDev williamr@2: The CMMFHwDevice implementation identifier. williamr@2: @param aMode williamr@2: The mode for which this object will be used. Any value other than EMMFStatePlaying, EMMFStateRecording or EMMFStateTonePlaying is unsupported. williamr@2: williamr@2: */ williamr@2: IMPORT_C void InitializeL(MDevSoundObserver& aDevSoundObserver, TUid aHWDev, TMMFState aMode); williamr@2: williamr@2: /** williamr@2: Initializes DevSound object for the mode aMode for processing audio data williamr@2: with hardware device supporting FourCC aDesiredFourCC. williamr@2: williamr@2: On completion of Initialization, the observer will be notified via call back williamr@2: InitializeComplete(). williamr@2: williamr@2: Leaves on failure. williamr@2: williamr@2: @param aDevSoundObserver williamr@2: A reference to DevSound Observer instance. williamr@2: @param aDesiredFourCC williamr@2: The CMMFHwDevice implementation FourCC code. williamr@2: @param aMode williamr@2: The mode for which this object will be used. Any value other than EMMFStatePlaying, EMMFStateRecording or EMMFStateTonePlaying is unsupported. williamr@2: williamr@2: */ williamr@2: IMPORT_C void InitializeL(MDevSoundObserver& aDevSoundObserver, TFourCC aDesiredFourCC, TMMFState aMode); williamr@2: williamr@2: /** williamr@2: Returns the supported Audio settings ie. encoding, sample rates, mono/stereo operation, buffer williamr@2: size etc. williamr@2: williamr@2: @return The device settings. williamr@2: */ williamr@2: IMPORT_C TMMFCapabilities Capabilities(); williamr@2: williamr@2: /** williamr@2: Returns the current device configuration. williamr@2: williamr@2: @return The device settings. williamr@2: */ williamr@2: IMPORT_C TMMFCapabilities Config() const; williamr@2: williamr@2: /** williamr@2: Configure CMMFDevSound object with the settings in aConfig. williamr@2: williamr@2: Use this to set sampling rate, encoding and mono/stereo. williamr@2: williamr@2: @param aCaps williamr@2: The attribute values to which CMMFDevSound object will be configured to. williamr@2: */ williamr@2: IMPORT_C void SetConfigL(const TMMFCapabilities& aCaps); williamr@2: williamr@2: /** williamr@2: Returns an integer representing the maximum volume device supports. williamr@2: williamr@2: This is the maximum value which can be passed to CMMFDevSound::SetVolume. williamr@2: williamr@2: @return The maximum volume. This value is platform dependent but is always greater than or equal williamr@2: to one. williamr@2: */ williamr@2: IMPORT_C TInt MaxVolume(); williamr@2: williamr@2: /** williamr@2: Returns an integer representing the current volume. williamr@2: williamr@2: @return The current volume level. williamr@2: */ williamr@2: IMPORT_C TInt Volume(); williamr@2: williamr@2: /** williamr@2: Changes the current playback volume to a specified value. williamr@2: williamr@2: The volume can be changed before or during playback and is effective williamr@2: immediately. williamr@2: williamr@2: @param aVolume williamr@2: The volume setting. This can be any value from 0 to the value williamr@2: returned by a call to CMMFDevSound::MaxVolume(). If the williamr@2: volume is not within this range, the volume is automatically set to williamr@2: minimum or maximum value based on the value that is being passed. williamr@2: Setting a zero value mutes the sound. Setting the maximum value williamr@2: results in the loudest possible sound. williamr@2: */ williamr@2: IMPORT_C void SetVolume(TInt aVolume); williamr@2: williamr@2: /** williamr@2: Returns an integer representing the maximum gain the device supports. williamr@2: williamr@2: This is the maximum value which can be passed to CMMFDevSound::SetGain. williamr@2: williamr@2: @return The maximum gain. This value is platform dependent but is always greater than or equal williamr@2: to one. williamr@2: */ williamr@2: IMPORT_C TInt MaxGain(); williamr@2: williamr@2: /** williamr@2: Returns an integer representing the current gain. williamr@2: williamr@2: @return The current gain level. williamr@2: */ williamr@2: IMPORT_C TInt Gain(); williamr@2: williamr@2: /** williamr@2: Changes the current recording gain to a specified value. williamr@2: williamr@2: The gain can be changed before or during recording and is effective williamr@2: immediately. williamr@2: williamr@2: @param aGain williamr@2: The gain setting. This can be any value from zero to the value williamr@2: returned by a call to CMMFDevSound::MaxGain(). If the williamr@2: volume is not within this range, the gain is automatically set to williamr@2: minimum or maximum value based on the value that is being passed. williamr@2: Setting a zero value mutes the sound. Setting the maximum value williamr@2: results in the loudest possible sound. williamr@2: */ williamr@2: IMPORT_C void SetGain(TInt aGain); williamr@2: williamr@2: /** williamr@2: Returns the speaker balance set for playing. williamr@2: williamr@2: Leaves on failure. williamr@2: williamr@2: @param aLeftPercentage williamr@2: On return contains the left speaker volume percentage. williamr@2: @param aRightPercentage williamr@2: On return contains the right speaker volume percentage. williamr@2: */ williamr@2: IMPORT_C void GetPlayBalanceL(TInt& aLeftPercentage, TInt& aRightPercentage); williamr@2: williamr@2: /** williamr@2: Sets the speaker balance for playing. williamr@2: williamr@2: The speaker balance can be changed before or during playback and is williamr@2: effective immediately. williamr@2: williamr@2: @param aLeftPercentage williamr@2: On return contains left speaker volume perecentage. This can be any williamr@2: value from zero to 100. Setting a zero value mutes the sound on left williamr@2: speaker. williamr@2: @param aRightPercentage williamr@2: On return contains right speaker volume perecentage. This can be any williamr@2: value from zero to 100. Setting a zero value mutes the sound on williamr@2: right speaker. williamr@2: */ williamr@2: IMPORT_C void SetPlayBalanceL(TInt aLeftPercentage, TInt aRightPercentage); williamr@2: williamr@2: /** williamr@2: Returns the microphone gain balance set for recording. williamr@2: williamr@2: Leaves on failure. williamr@2: williamr@2: @param aLeftPercentage williamr@2: On return contains the left microphone gain percentage. williamr@2: @param aRightPercentage williamr@2: On return contains the right microphone gain percentage. williamr@2: */ williamr@2: IMPORT_C void GetRecordBalanceL(TInt& aLeftPercentage, TInt& aRightPercentage); williamr@2: williamr@2: /** williamr@2: Sets the microphone gain balance for recording. williamr@2: williamr@2: The microphone gain balance can be changed before or during recording and williamr@2: is effective immediately. williamr@2: williamr@2: @param aLeftPercentage williamr@2: The left microphone gain precentage. This can be any value from zero to williamr@2: 100. Setting a zero value mutes the gain on left microphone. williamr@2: @param aRightPercentage williamr@2: The right microphone gain precentage. This can be any value from zero to williamr@2: 100. Setting a zero value mutes the gain on right microphone. williamr@2: */ williamr@2: IMPORT_C void SetRecordBalanceL(TInt aLeftPercentage, TInt aRightPercentage); williamr@2: williamr@2: /** williamr@2: Initializes the audio device and starts the play process. williamr@2: williamr@2: This function queries and acquires the audio policy before initializing audio device. If there was williamr@2: an error during policy initialization, PlayError() function will be called on the observer with williamr@2: error code KErrAccessDenied, otherwise BufferToBeFilled() function will be called with a buffer williamr@2: reference. After reading data into the buffer reference passed, the client should call williamr@2: PlayData() to play data. williamr@2: williamr@2: The amount of data that can be played is specified in williamr@2: CMMFBuffer::RequestSize(). Any data that is read into buffer beyond this williamr@2: size will be ignored. williamr@2: williamr@2: Leaves on failure. williamr@2: williamr@2: @see MDevSoundObserver::PlayError() williamr@2: @see MDevSoundObserver::BufferToBeFilled() williamr@2: */ williamr@2: IMPORT_C void PlayInitL(); williamr@2: williamr@2: /** williamr@2: Initializes audio device and starts the recording process. williamr@2: williamr@2: This function queries and acquires the audio policy before initializing audio device. If there williamr@2: was an error during policy initialization, RecordError() function will be called on the observer williamr@2: with error code KErrAccessDenied, otherwise BufferToBeEmptied() function will be called with a williamr@2: buffer reference. This buffer contains recorded or encoded data. After processing data in the williamr@2: buffer reference passed, the client should call RecordData() to continue recording process. williamr@2: williamr@2: The amount of data that is available is specified in CMMFBuffer::RequestSize(). williamr@2: williamr@2: Leaves on failure. williamr@2: williamr@2: @see MDevSoundObserver::RecordError() williamr@2: @see MDevSoundObserver::BufferToBeEmptied() williamr@2: williamr@2: @capability UserEnvironment williamr@2: For recording - the requesting client process must have the williamr@2: UserEnvironment capability. williamr@2: */ williamr@2: IMPORT_C void RecordInitL(); williamr@2: williamr@2: /** williamr@2: Plays data in the buffer at the current volume. williamr@2: williamr@2: The client should fill the buffer with audio data before calling this function. The observer gets williamr@2: a reference to the buffer along with the callback function BufferToBeFilled(). When playing of williamr@2: the audio sample is complete, successfully or otherwise, the function PlayError() on the williamr@2: observer is called. williamr@2: williamr@2: The last buffer of the audio stream being played should have the last buffer flag set using williamr@2: CMMFBuffer::SetLastBuffer(TBool). If a subsequent attempt to play the clip is made, this flag williamr@2: will need resetting by the client. williamr@2: williamr@2: @see MDevSoundObserver::PlayError() williamr@2: */ williamr@2: IMPORT_C void PlayData(); williamr@2: williamr@2: /** williamr@2: Contine the process of recording. williamr@2: williamr@2: Once the buffer is filled with recorded data, the Observer gets a reference to the buffer along williamr@2: with the callback function BufferToBeEmptied(). After processing the buffer (copying over to a williamr@2: different buffer or writing to file) the client should call this function to continue the williamr@2: recording process. williamr@2: williamr@2: @capability UserEnvironment williamr@2: For recording - the requesting client process must have the williamr@2: UserEnvironment capability. williamr@2: */ williamr@2: IMPORT_C void RecordData(); williamr@2: williamr@2: /** williamr@2: Stops the ongoing operation (Play, Record, TonePlay, Convert). williamr@2: williamr@2: This function should be synchronous and invoke no callbacks through MDevSoundObserver. williamr@2: */ williamr@2: IMPORT_C void Stop(); williamr@2: williamr@2: /** williamr@2: Temporarily Stops the ongoing operation (Play, Record, TonePlay, Convert). williamr@2: williamr@2: The behaviour of Pause() is currently undefined when the initialisation mode williamr@2: is not EMMFStateRecording, consequently different DevSound implementations exhibit williamr@2: different behaviour for pause during play. For this reason, it is recommended that williamr@2: when pausing of audio during playing is required, Stop() is used instead of the call williamr@2: to Pause(). To resume audio playing after Stop(), call PlayInitL(). Among other things, williamr@2: this will internally reset the SamplesPlayed() result and the calling code may need to williamr@2: remember the previous result to give the correct "samples played from start" value. williamr@2: williamr@2: In the case of record, Pause is taken to mean halt any further recording williamr@2: but continue to call the MDevSoundObserver::BufferToBeEmptied() passing williamr@2: already recorded buffers. The last buffer flag should be set when williamr@2: all recorded buffers have been flushed. williamr@2: williamr@2: @see CMMFDevSound::Stop() williamr@2: @see CMMFDevSound::PlayInitL() williamr@2: @see CMMFDevSound::SamplesPlayed() williamr@2: */ williamr@2: IMPORT_C void Pause(); williamr@2: williamr@2: /** williamr@2: Returns the number samples recorded so far. williamr@2: williamr@2: @return The samples recorded. williamr@2: */ williamr@2: IMPORT_C TInt SamplesRecorded(); williamr@2: williamr@2: /** williamr@2: Returns the number of samples played so far. williamr@2: williamr@2: @return The samples played. williamr@2: */ williamr@2: IMPORT_C TInt SamplesPlayed(); williamr@2: williamr@2: /** williamr@2: Initializes the audio device and starts playing a tone. The tone is played with the williamr@2: frequency and duration specified. williamr@2: williamr@2: Leaves on failure. williamr@2: williamr@2: @param aFrequency williamr@2: The frequency at which the tone will be played. williamr@2: @param aDuration williamr@2: The period over which the tone will be played. A zero value causes williamr@2: the no tone to be played. williamr@2: */ williamr@2: IMPORT_C void PlayToneL(TInt aFrequency, const TTimeIntervalMicroSeconds& aDuration); williamr@2: williamr@2: /** williamr@2: Initializes audio device and starts playing a dual tone. williamr@2: williamr@2: The generated tone consists of two sine waves of different frequencies williamr@2: summed together. williamr@2: williamr@2: Dual Tone is played with the specified frequencies and for the specified duration. williamr@2: williamr@2: @param aFrequencyOne williamr@2: The first frequency of dual tone. williamr@2: @param aFrequencyTwo williamr@2: The second frequency of dual tone williamr@2: @param aDuration williamr@2: The period over which the tone will be played. A zero value causes williamr@2: the no tone to be played (Verify this with test app). williamr@2: */ williamr@2: IMPORT_C void PlayDualToneL(TInt aFrequencyOne, TInt aFrequencyTwo, const TTimeIntervalMicroSeconds& aDuration); williamr@2: williamr@2: /** williamr@2: Initializes the audio device and starts playing the DTMF string aDTMFString. williamr@2: williamr@2: Leaves on failure. williamr@2: williamr@2: @param aDTMFString williamr@2: The DTMF sequence in a descriptor. williamr@2: */ williamr@2: IMPORT_C void PlayDTMFStringL(const TDesC& aDTMFString); williamr@2: williamr@2: /** williamr@2: Initializes the audio device and starts playing a tone sequence. williamr@2: williamr@2: Leaves on failure. williamr@2: williamr@2: @param aData williamr@2: The tone sequence in a descriptor. williamr@2: */ williamr@2: IMPORT_C void PlayToneSequenceL(const TDesC8& aData); williamr@2: williamr@2: /** williamr@2: Initializes the audio device and starts playing the specified pre-defined tone williamr@2: sequence. williamr@2: williamr@2: Leaves on failure. williamr@2: williamr@2: @param aSequenceNumber williamr@2: The index identifying the specific pre-defined tone sequence. Index williamr@2: values are relative to zero. williamr@2: This can be any value from zero to the value returned by a call to williamr@2: FixedSequenceCount() - 1. williamr@2: The function raises a panic if the sequence number is not within this williamr@2: range. williamr@2: @see FixedSequenceCount() williamr@2: */ williamr@2: IMPORT_C void PlayFixedSequenceL(TInt aSequenceNumber); williamr@2: williamr@2: /** williamr@2: Defines the number of times the audio is to be repeated during the tone williamr@2: playback operation. williamr@2: williamr@2: A period of silence can follow each playing of a tone. The tone playing can williamr@2: be repeated indefinitely. williamr@2: williamr@2: @param aRepeatCount williamr@2: The number of times the tone, together with the trailing silence, williamr@2: is to be repeated. If this is set to KMdaRepeatForever, then the williamr@2: tone, together with the trailing silence, is repeated indefinitely williamr@2: or until Stop() is called. If this is set to zero, then the tone is williamr@2: not repeated. williamr@2: @param aRepeatTrailingSilence williamr@2: An interval of silence which will be played after each tone. williamr@2: Supported only during tone playing. williamr@2: */ williamr@2: IMPORT_C void SetToneRepeats(TInt aRepeatCount, williamr@2: const TTimeIntervalMicroSeconds& aRepeatTrailingSilence); williamr@2: williamr@2: /** williamr@2: Defines the duration of tone on, tone off and tone pause to be used during the williamr@2: DTMF tone playback operation. williamr@2: williamr@2: Supported only during tone playing. williamr@2: williamr@2: @param aToneOnLength williamr@2: The period over which the tone will be played. If this is set to williamr@2: zero, then the tone is not played. williamr@2: @param aToneOffLength williamr@2: The period over which the no tone will be played. williamr@2: @param aPauseLength williamr@2: The period over which the tone playing will be paused. williamr@2: */ williamr@2: IMPORT_C void SetDTMFLengths(TTimeIntervalMicroSeconds32& aToneOnLength, williamr@2: TTimeIntervalMicroSeconds32& aToneOffLength, williamr@2: TTimeIntervalMicroSeconds32& aPauseLength); williamr@2: williamr@2: /** williamr@2: Defines the period over which the volume level is to rise smoothly from williamr@2: nothing to the normal volume level. williamr@2: williamr@2: The function is only available while the tone is playing. williamr@2: williamr@2: @param aRampDuration williamr@2: The period over which the volume is to rise. A zero value causes williamr@2: the tone sample to be played at the normal level for the full williamr@2: duration of the playback. A value, which is longer than the duration williamr@2: of the tone sample means that the sample never reaches its normal williamr@2: volume level. williamr@2: */ williamr@2: IMPORT_C void SetVolumeRamp(const TTimeIntervalMicroSeconds& aRampDuration); williamr@2: williamr@2: /** williamr@2: Defines the priority settings that should be used for this instance. williamr@2: williamr@2: @param aPrioritySettings williamr@2: A class type representing the client's priority, priority preference and state. williamr@2: */ williamr@2: IMPORT_C void SetPrioritySettings(const TMMFPrioritySettings& aPrioritySettings); williamr@2: williamr@2: /** williamr@2: Retrieves a custom interface to the device. williamr@2: williamr@2: @param aInterfaceId williamr@2: The interface UID, defined with the custom interface. williamr@2: williamr@2: @return A pointer to the interface implementation, or NULL if the device does not williamr@2: implement the interface requested. The return value must be cast to the williamr@2: correct type by the user.The user should be careful while caching the custom interface pointer, williamr@2: as in some situations the lower level custom interface pointer may become NULL. williamr@2: */ williamr@2: IMPORT_C TAny* CustomInterface(TUid aInterfaceId); williamr@2: williamr@2: /** williamr@2: Returns the number of available pre-defined tone sequences. williamr@2: williamr@2: This is the number of fixed sequence supported by DevSound by default. williamr@2: williamr@2: @return The fixed sequence count. This value is implementation dependent but is always greater williamr@2: than or equal to zero. williamr@2: */ williamr@2: IMPORT_C TInt FixedSequenceCount(); williamr@2: williamr@2: /** williamr@2: Returns the name assigned to a specific pre-defined tone sequence. williamr@2: williamr@2: This is the number of the fixed sequence supported by DevSound by default. williamr@2: williamr@2: The function raises a panic if sequence number specified is invalid. williamr@2: williamr@2: @param aSequenceNumber williamr@2: The index identifying the specific pre-defined tone sequence. Index values are relative williamr@2: to zero. This can be any value from zero to the value returned by a call to williamr@2: FixedSequenceCount() - 1. williamr@2: The function raises a panic if sequence number is not within this williamr@2: range. williamr@2: williamr@2: @return A reference to a Descriptor containing the fixed sequence name indexed by williamr@2: aSequenceNumber. williamr@2: williamr@2: @see FixedSequenceCount() williamr@2: */ williamr@2: IMPORT_C const TDesC& FixedSequenceName(TInt aSequenceNumber); williamr@2: williamr@2: /** williamr@2: Returns a list of the supported input datatypes that can be sent to DevSound for playing audio. williamr@2: The datatypes returned are those that the DevSound supports given the priority settings passed williamr@2: in aPrioritySettings. williamr@2: williamr@2: Note that if no supported data types are found this does not constitute failure, the function will williamr@2: return normally with no entries in aSupportedDataTypes. williamr@2: williamr@2: @param aSupportedDataTypes williamr@2: The array of supported data types that will be filled in by this function. williamr@2: The supported data types of the DevSound are in the form of an array williamr@2: of TFourCC codes. Any existing entries in the array will be overwritten on williamr@2: calling this function. If no supported data types are found given the priority williamr@2: settings, then the aSupportedDatatypes array will have zero entries. williamr@2: @param aPrioritySettings williamr@2: The priority settings used to determine the supported datatypes. Note this williamr@2: does not set the priority settings. For input datatypes the iState member williamr@2: of the priority settings would be expected to be either williamr@2: EMMFStatePlaying or EMMFStatePlayingRecording. The priority settings may williamr@2: effect the supported datatypes depending on the audio routing. williamr@2: */ williamr@2: IMPORT_C void GetSupportedInputDataTypesL(RArray& aSupportedDataTypes, const TMMFPrioritySettings& aPrioritySettings) const; williamr@2: williamr@2: /** williamr@2: Returns a list of the supported output dataypes that can be received from DevSound for williamr@2: recording audio. The datatypes returned are those that the DevSound supports given the priority williamr@2: settings passed in aPrioritySettings. williamr@2: williamr@2: Note that if no supported data types are found this does not constitute failure, the function will williamr@2: return normally with no entries in aSupportedDataTypes. williamr@2: williamr@2: @param aSupportedDataTypes williamr@2: The array of supported data types that will be filled in by this function. williamr@2: The supported datatypes of the DevSound are in the form of an array williamr@2: of TFourCC codes. williamr@2: Any existing entries in the array will be overwritten on calling this function. williamr@2: If no supported datatypes are found given the priority settings, then williamr@2: the aSupportedDatatypes array will have zero entries. williamr@2: @param aPrioritySettings williamr@2: The priority settings used to determine the supported data types. Note this williamr@2: does not set the priority settings. For output data types the iState member williamr@2: of the priority settings would expected to be either williamr@2: EMMFStateRecording or EMMFStatePlayingRecording. The priority settings may williamr@2: effect the supported datatypes depending on the audio routing. williamr@2: */ williamr@2: IMPORT_C void GetSupportedOutputDataTypesL(RArray& aSupportedDataTypes, const TMMFPrioritySettings& aPrioritySettings) const; williamr@2: williamr@2: /** williamr@2: Registers the client for notification of resource avalibility. williamr@2: williamr@2: @param aEventType williamr@2: The Notification event type for which the client needs notification. williamr@2: @param aNotificationRegistrationData williamr@2: The Notification Registration data has been reserved for future use and its value should be always NULL williamr@2: @return An error code indicating if the function call was successful. KErrNone on success, williamr@2: KErrNotSupported if the event type is not supported, KErrArgument if the notification data williamr@2: is not null otherwise another of the system-wide error codes. williamr@2: */ williamr@2: inline TInt RegisterAsClient(TUid aEventType, const TDesC8& aNotificationRegistrationData = KNullDesC8); williamr@2: williamr@2: /** williamr@2: Cancels the Registered Notification. williamr@2: williamr@2: @param aEventType williamr@2: The Event type need to cancel williamr@2: @return An error code indicating if the function call was successful. KErrNone on success, KErrNotSupported williamr@2: if the event type is not supported otherwise another of the system-wide error codes. williamr@2: */ williamr@2: inline TInt CancelRegisterAsClient(TUid aEventType); williamr@2: williamr@2: /** williamr@2: Returns the Notification data which the client needs to resume playing. williamr@2: williamr@2: @param aEventType williamr@2: The Event type for which to get notification data williamr@2: @param aNotificationData williamr@2: The reference data for which the client needs to resume the play. The actual data depends on the event type. williamr@2: Note that for the event type 'KMMFEventCategoryAudioResourceAvailable' the package buffer returned williamr@2: is TMMFTimeIntervalMicroSecondsPckg,but the contents should be converted to an integer and williamr@2: interpreted as the data returned is samples played ,but not as a microsecond value. williamr@2: @return An error code indicating if the function call was successful. KErrNone on success, otherwise williamr@2: another of the system-wide error codes. williamr@2: */ williamr@2: inline TInt GetResourceNotificationData(TUid aEventType,TDes8& aNotificationData); williamr@2: williamr@2: /** williamr@2: Wait for the clients to resume play back even after the default timeout expires. williamr@2: Unless the client cancels the notification request or completes no other client gets williamr@2: notification. williamr@2: williamr@2: @return An error code indicating if the function call was successful. KErrNone on success, williamr@2: KErrPermissionDenied if the client does not have MultimediaDD capaility, otherwise williamr@2: another of the system-wide error codes. williamr@2: */ williamr@2: inline TInt WillResumePlay(); williamr@2: williamr@2: /** williamr@2: @publishedPartner williamr@2: @prototype williamr@2: williamr@2: Empties the play buffers below DevSound without causing the codec to be deleted. williamr@2: williamr@2: @return An error code indicating if the function call was successful. KErrNone on success, williamr@2: KErrNotSupported if called in a mode other than EMMFStatePlaying or if the function is otherwise not supported, williamr@2: KErrNotReady if this is called before playing, williamr@2: otherwise another of the system-wide error codes. williamr@2: If this function is not supported, it is advised to use Stop(). williamr@2: */ williamr@2: inline TInt EmptyBuffers(); williamr@2: williamr@2: /** Cancels the initialization process of a CMMFDevSound object williamr@2: williamr@2: @return An error code indicating if the function call was successful. williamr@2: KErrNone on success, williamr@2: KerrNotReady if this is called before InitializeL() call or after williamr@2: the object has been initialized, williamr@2: */ williamr@2: inline TInt CancelInitialize(); williamr@2: williamr@2: /** williamr@2: Sets client thread info for devsound to make proper policy and routing decisions williamr@2: williamr@2: @param aTid williamr@2: The thread Id of real client. williamr@2: williamr@2: @capability MultimediaDD williamr@2: A process requires MultimediaDD capability to make this call. williamr@2: */ williamr@2: inline TInt SetClientThreadInfo(TThreadId aTid); williamr@2: williamr@2: /** williamr@2: Retrieves the current play time from the audio renderer williamr@2: williamr@2: @param aTime williamr@2: A reference to TTimeIntervalMicroSeconds object which will be filled with the current play time by this function. williamr@2: @return An error code indicating if the function call was successful. williamr@2: KErrNone on success, williamr@2: KErrNotSupported if the underlying devsound implementation or the HwDevice does not support this API, williamr@2: otherwise any of the system-wide error codes. williamr@2: If this function is not supported, SamplesPlayed() needs to be used instead. williamr@2: williamr@2: @see IsGetTimePlayedSupported() williamr@2: */ williamr@2: inline TInt GetTimePlayed(TTimeIntervalMicroSeconds& aTime); williamr@2: williamr@2: /** williamr@2: This method can be used by devsound clients to check if the devsound implementation supports williamr@2: GetTimePlayed API. If this method returns EFalse, SamplesPlayed needs to be used. williamr@2: williamr@2: @return ETrue if the underlying devsound implementation supports GetTimePlayed API, williamr@2: EFalse if the the underlying devsound implementation does not support GetTimePlayed API williamr@2: williamr@2: @see GetTimePlayed() williamr@2: */ williamr@2: inline TBool IsGetTimePlayedSupported(); williamr@2: williamr@2: /** williamr@2: This method can be used by devsound clients to check if the devsound implementation ignores the underflow williamr@2: errors from the sound driver and does not propagate them to its clients. williamr@2: williamr@2: @return ETrue if devsound ignores all the underflow errors from the sound driver except for the last buffer williamr@2: That means DevSound propagates the underflow error from sound driver to its clients only when williamr@2: client sets the last buffer flag on the CMMFBuffer type buffer. williamr@2: EFalse if devsound propagates the underflow errors from the sound driver in all the cases williamr@2: williamr@2: */ williamr@2: inline TBool QueryIgnoresUnderflow(); williamr@2: williamr@2: /** williamr@2: This method can be used by devsound clients to check if current configuration supports resume williamr@2: This call is only valid when DevSound is initialized williamr@2: @return ETrue if current format does supports resume williamr@2: EFalse otherwise williamr@2: */ williamr@2: inline TBool IsResumeSupported(); williamr@2: williamr@2: /** williamr@2: Resume play back, recording or tone playing after this has been paused williamr@2: @return An error code indicating if the function call was successful. williamr@2: KErrNone on success, williamr@2: KErrNotSupported if current format configuration does not support this functionality williamr@2: KErrNotReady if DevSound is not paused williamr@2: */ williamr@2: inline TInt Resume(); williamr@2: williamr@2: protected: williamr@2: williamr@2: /** williamr@2: Default Constructor. williamr@2: */ williamr@2: //So that nobody can extend derive from CMMFDevSound. williamr@2: CMMFDevSound(); williamr@2: williamr@2: /** williamr@2: Second phase constructor. williamr@2: */ williamr@2: void ConstructL(); williamr@2: williamr@2: class CBody; williamr@2: williamr@2: /** williamr@2: DevSound body williamr@2: */ williamr@2: CBody* iBody; williamr@2: }; williamr@2: williamr@2: inline void MDevSoundObserver::SendEventToClient(const TMMFEvent& /*aEvent*/) williamr@2: { williamr@2: } williamr@2: williamr@2: #include williamr@2: williamr@2: #endif // __SOUNDDEVICE_H__