Update contrib.
2 * Copyright (c) 2006-2009 Nokia Corporation and/or its subsidiary(-ies).
4 * This component and the accompanying materials are made available
5 * under the terms of "Eclipse Public License v1.0"
6 * which accompanies this distribution, and is available
7 * at the URL "http://www.eclipse.org/legal/epl-v10.html".
9 * Initial Contributors:
10 * Nokia Corporation - initial contribution.
20 #ifndef MMFDEVSOUNDADAPTATIONBODY_H
21 #define MMFDEVSOUNDADAPTATIONBODY_H
24 #include <mmf/server/mmfhwdevice.h>
25 #include <a3f/a3f_trace_utils.h>
26 #include "mmfdevsoundadaptation.h"
27 #include <a3f/tonedata.h>
28 #include <a3f/audioprocessingunittypeuids.h>
32 class CDevAudioControl;
33 class MGlobalProperties;
36 const TInt KDevsoundDefaultMaxGain = 10;
37 const TUint KDevSoundMaxCaps = 0xFFFFFFFF;
39 const TUint KDataForPlay = 0;
40 const TUint KDataForRecord = 1;
43 * Class implementing CMMFDevSoundAdaptation behaviour.
45 * @lib mmfdevsoundadaptation.lib
47 class CMMFDevSoundAdaptation::CBody : public CBase
49 friend class CMMFDevSoundAdaptation;
53 static CBody* NewL(MDevSoundAdaptationObserver& aDevSoundObserver,
54 MGlobalProperties& aGlobalProperties);
58 public: // New functions
61 * 2nd phase async open operation
66 * Initializes to raw audio data PCM16 and Sampling Rate of 8 KHz.
67 * On completion of Initialization, calls InitializeComplete() on
71 * @param MDevSoundAdaptationObserver& aDevSoundObserver A reference to DevSound
73 * @param TMMFState aMode Mode for which this object will be used.
76 void InitializeL(TMMFState aMode);
79 * Initializes DevSound object for the mode aMode for processing audio
80 * data with hardware device aHWDev.
81 * On completion of Initialization, calls InitializeComplete() on
85 * @param MDevSoundAdaptationObserver& aDevSoundObserver A reference to DevSound
87 * @param TUid aHWDev The CMMFHwDevice implementation identifier.
88 * @param TMMFState aMode The mode for which this object will be used
91 void InitializeL(TUid aHWDev, TMMFState aMode);
94 * Initializes DevSound object for the mode aMode for processing audio
95 * data with hardware device supporting FourCC aDesiredFourCC.
98 * @param MDevSoundAdaptationObserver& aDevSoundObserver A reference to DevSound
100 * @param TFourCC aDesiredFourCC The CMMFHwDevice implementation FourCC
102 * @param TMMFState aMode The mode for which this object will be used
103 * @return KErrNone if successfull, else corresponding error code
106 void InitializeL(TFourCC aDesiredFourCC,
110 * Initializes DevSound object with codec format aFormat
113 * @param aDevSoundObserver A reference to DevSound Observer instance.
114 * @param aFormat codec format
115 * @param aMode The mode for which this object will be used
117 void DoInitializeL(TUid aFormat,
121 * Cancels the initialization of a DevSound object.
123 * @return An error code indicating if the function call was successful.
124 * KErrNone on success,
125 * KerrNotReady if this is called before InitializeL() call or after
126 * the object has been initialized,
128 TInt CancelInitialize();
131 * Returns the supported Audio settings ie. encoding, sample rates,
132 * mono/stereo operation, buffer size etc..
134 * @return TMMFCapabilities The device settings.
136 TInt Capabilities(TMMFCapabilities& aCap);
139 * Returns the current device configuration.
141 * @return TMMFCapabilities The device settings.
143 TMMFCapabilities Config() const;
146 * Configure CMMFDevSound object with the settings in aConfig. Use this
147 * to set sampling rate, encoding and mono/stereo.
150 * @param const TMMFCapabilities& aConfig The attribute values to which
151 * CMMFDevSound object will be configured to.
154 void SetConfigL(const TMMFCapabilities& aCaps);
157 * Returns an integer representing the maximum volume device supports.
158 * This is the maximum value which can be passed to
159 * CMMFDevSound::SetVolume.
161 * @return TInt The maximum volume. This value is platform dependent but
162 * is always greater than or equal to one.
167 * Returns an integer representing the current volume.
169 * @return TInt The current volume level.
174 * Changes the current playback volume to a specified value. The volume
175 * can be changed before or during playback and is effective immediately.
177 * @param aVolume The volume setting. This can be any value from 0
178 * to the value returned by a call to
179 * CMMFDevSound::MaxVolume(). If the volume is not
180 * within this range, the volume is automatically set
181 * to minimum or maximum value based on the value
182 * that is being passed. Setting a zero value mutes
183 * the sound. Setting the maximum value results in
184 * the loudest possible sound.
185 * @param aAsyncCompletion Returns ETrue to say the call is asynchronous, with result sent
186 * to AsynchronousOperationComplete()
187 * @return KErrNone if successful, otherwise system-wide error code
189 TInt SetVolume(TInt aVolume, TBool& aAyncCompletion);
192 * Gets the maximum gain the device supports.
193 * This is the maximum value which can be passed to CMMFDevSound::SetGain
200 * Returns an integer representing the current gain.
202 * @return TInt The current gain level.
207 * Changes the current recording gain to a specified value. The gain can
208 * be changed before or during recording and is effective immediately.
210 * @param TInt aGain The gain setting. This can be any value from zero to
211 * the value returned by a call to
212 * CMMFDevSound::MaxGain(). If the volume
213 * is not within this range, the gain is automatically
214 * set to minimum or maximum value based on the value
215 * that is being passed. Setting a zero value mutes the
216 * sound. Setting the maximum value results in the
217 * loudest possible sound.
218 * @param aAsyncCompletion Returns ETrue to say the call is asynchronous, with result sent
219 * to AsynchronousOperationComplete()
222 TInt SetGain(TInt aGain, TBool& aAyncCompletion);
225 * Returns the speaker balance set for playing.
228 * @param TInt &aLeftPercentage On return contains the left speaker
230 * @param TInt &aRightPercentage On return contains the right speaker
234 void GetPlayBalanceL(TInt& aLeftPercentage, TInt& aRightPercentage);
237 * Sets the speaker balance for playing. The speaker balance can be
238 * changed before or during playback and is effective immediately.
241 * @param TInt aLeftPercentage The left speaker volume percentage. This
242 * can be any value from zero to 100. Setting
243 * a zero value mutes the sound on left
245 * @param TInt aRightPercentage The right speaker volume percentage.
246 * This can be any value from zero to 100.
247 * Setting a zero value mutes the sound on
249 * @param aAsyncCompletion Returns ETrue to say the call is asynchronous, with result sent
250 * to AsynchronousOperationComplete()
253 void SetPlayBalanceL(TInt aLeftPercentage, TInt aRightPercentage, TBool& aAsyncCompletion);
256 * Returns the microphone gain balance set for recording.
259 * @param TInt &aLeftPercentage On return contains the left microphone
261 * @param TInt &aRightPercentage On return contains the right microphone
265 void GetRecordBalanceL(TInt& aLeftPercentage, TInt& aRightPercentage);
268 * Sets the microphone balance for recording. The microphone balance can
269 * be changed before or during recording and is effective immediately.
272 * @param TInt aLeftPercentage The left microphone gain percentage. This
273 * can be any value from zero to 100. Setting
274 * a zero value mutes the sound from left
276 * @param TInt aRightPercentage The right microphone gain percentage.
277 * This can be any value from zero to 100.
278 * Setting a zero value mutes the sound from
280 * @param aAsyncCompletion Returns ETrue to say the call is asynchronous, with result sent
281 * to AsynchronousOperationComplete()
284 void SetRecordBalanceL(TInt aLeftPercentage, TInt aRightPercentage, TBool& aAsyncCompletion);
287 * Initializes the audio device and starts the play process. This
288 * function queries and acquires the audio policy before initializing
289 * audio device. If there was an error during policy initialization,
290 * PlayError() function will be called on the observer with error code
291 * KErrAccessDenied, otherwise BufferToBeFilled() function will be called
292 * with a buffer reference. After reading data into the buffer reference
293 * passed, the client should call PlayData() to play data.
294 * The amount of data that can be played is specified in
295 * CMMFBuffer::RequestSize(). Any data that is read into buffer beyond
296 * this size will be ignored.
304 * Initializes the audio device and starts the record process. This
305 * function queries and acquires the audio policy before initializing
306 * audio device. If there was an error during policy initialization,
307 * RecordError() function will be called on the observer with error code
308 * KErrAccessDenied, otherwise BufferToBeEmptied() function will be called
309 * with a buffer reference. This buffer contains recorded or encoded
310 * data. After processing data in the buffer reference passed, the client
311 * should call RecordData() to continue recording process.
312 * The amount of data that is available is specified in
313 * CMMFBuffer::RequestSize().
321 * Plays data in the buffer at the current volume.
322 * The client should fill the buffer with audio data before calling this
323 * function. The observer gets a reference to the buffer along with the
324 * callback function BufferToBeFilled(). When playing of the audio sample
325 * is complete, successfully or otherwise, the function PlayError() on
326 * the observer is called.
327 * The last buffer of the audio stream being played should have the last
328 * buffer flag set using CMMFBuffer::SetLastBuffer(TBool). If a
329 * subsequent attempt to play the clip is made, this flag will need
330 * resetting by the client.
336 * Contine the process of recording.
337 * Once the buffer is filled with recorded data, the Observer gets a
338 * reference to the buffer along with the callback function
339 * BufferToBeEmptied(). After processing the buffer (copying over to a
340 * different buffer or writing to file) the client should call this
341 * function to continue the recording process.
347 * Stops the ongoing operation (Play, Record, TonePlay).
349 * @return KErrNone if successful, system wide error otherwise
354 * Temporarily Stops the ongoing operation (Play, Record, TonePlay).
356 * @return KErrNone if successful, system wide error otherwise
361 * Returns the Sample recorded so far
363 * @return TInt Returns the samples recorded.
365 TInt SamplesRecorded();
368 * Returns the Sample played so far
370 * @return TInt Returns the samples played.
372 TInt SamplesPlayed();
375 * Initializes the audio device and starts playing a tone. The tone is
376 * played with the frequency and duration specified.
379 * @param TInt aFrequency The frequency at which the tone will be played.
380 * @param const TTimeIntervalMicroSeconds &aDuration The period over
381 * which the tone will be played. A zero value causes the no tone
385 void PlayToneL(TInt aFrequency, const TTimeIntervalMicroSeconds& aDuration);
388 * Initializes audio device and starts playing a dual tone. Dual Tone is
389 * played with the specified frequencies and for the specified duration.
392 * @param TInt aFrequencyOne The first frequency of dual tone.
393 * @param TInt aFrequencyTwo The second frequency of dual tone.
394 * @param const TTimeIntervalMicroSeconds &aDuration The period over
395 * which the tone will be played. A zero value causes the no tone
399 void PlayDualToneL(TInt aFrequencyOne,
401 const TTimeIntervalMicroSeconds& aDuration);
404 * Initializes the audio device and starts playing the DTMF string
408 * @param const TDesC &aDTMFString The DTMF sequence in a descriptor.
411 void PlayDTMFStringL(const TDesC& aDTMFString);
414 * Initializes the audio device and starts playing a tone sequence.
417 * @param const TDesC8 &aData The tone sequence in a descriptor.
420 void PlayToneSequenceL(const TDesC8& aData);
423 * Initializes the audio device and starts playing the specified
424 * pre-defined tone sequence.
427 * @param TInt aSequenceNumber The index identifying the specific
428 * pre-defined tone sequence. Index values are relative to zero.
429 * This can be any value from zero to the value returned by a call
430 * to FixedSequenceCount() - 1. The function raises a panic if the
431 * sequence number is not within this range.
434 void PlayFixedSequenceL(TInt aSequenceNumber);
437 * Defines the number of times the audio is to be repeated during the
438 * tone playback operation. A period of silence can follow each playing
439 * of a tone. The tone playing can be repeated indefinitely
441 * @param TInt aRepeatCount The number of times the tone, together with
442 * the trailing silence, is to be repeated. If this is set to
443 * KMdaRepeatForever, then the tone, together with the trailing
444 * silence, is repeated indefinitely or until Stop() is called.
445 * If this is set to zero, then the tone is not repeated.
446 * @param const TTimeIntervalMicroSeconds &aRepeatTrailingSilence An
447 * interval of silence which will be played after each tone.
448 * Supported only during tone playing.
449 * @return KErrNone if successful, system wide error otherwise
451 TInt SetToneRepeats(TInt aRepeatCount,
452 const TTimeIntervalMicroSeconds& aRepeatTrailingSilence);
455 * Defines the duration of tone on, tone off and tone pause to be used
456 * during the DTMF tone playback operation.
457 * Supported only during tone playing.
459 * @param TTimeIntervalMicroSeconds32 &aToneOnLength The period over
460 * which the tone will be played. If this is set to zero, then the
461 * tone is not played.
462 * @param TTimeIntervalMicroSeconds32 &aToneOffLength The period over
463 * which the no tone will be played.
464 * @param TTimeIntervalMicroSeconds32 &aPauseLength The period over which
465 * the tone playing will be paused.
466 * @return KErrNone if successful, system wide error otherwise
468 TInt SetDTMFLengths(TTimeIntervalMicroSeconds32& aToneOnLength,
469 TTimeIntervalMicroSeconds32& aToneOffLength,
470 TTimeIntervalMicroSeconds32& aPauseLength);
473 * Defines the period over which the volume level is to rise smoothly
474 * from nothing to the normal volume level.
475 * The function is only available before playing.
477 * @param const TTimeIntervalMicroSeconds &aRampDuration The period over
478 * which the volume is to rise. A zero value causes the tone
479 * sample to be played at the normal level for the full duration
480 * of the playback. A value, which is longer than the duration of
481 * the tone sample means that the sample never reaches its normal
483 * @return KErrNone if successful, system wide error otherwise
485 TInt SetVolumeRamp(const TTimeIntervalMicroSeconds& aRampDuration);
488 * Defines the priority settings that should be used for this instance.
490 * @param const TMMFPrioritySettings &aPrioritySettings A class type
491 * representing the client's priority, priority preference and
493 * @return KErrNone if successful, system wide error otherwise
495 TInt SetPrioritySettings(const TMMFPrioritySettings& aPrioritySettings);
498 * Retrieves a custom interface to the device.
500 * @param TUid aInterfaceId The interface UID, defined with the custom
502 * @return TAny* A pointer to the interface implementation, or NULL if
503 * the device does not implement the interface requested. The
504 * return value must be cast to the correct type by the user.
506 TAny* CustomInterface(TUid aInterfaceId);
509 * Returns the number of available pre-defined tone sequences.
510 * This is the number of fixed sequence supported by DevSound by default.
512 * @return TInt The fixed sequence count. This value is implementation
515 TInt FixedSequenceCount();
518 * Returns the name assigned to a specific pre-defined tone sequence.
519 * This is the number of the fixed sequence supported by DevSound by
521 * The function raises a panic if sequence number specified is invalid.
523 * @param TInt aSequenceNumber The index identifying the specific
524 * pre-defined tone sequence. Index values are relative to zero.
525 * This can be any value from zero to the value returned by a call
526 * to CMdaAudioPlayerUtility::FixedSequenceCount() - 1. The
527 * function raises a panic if sequence number is not within this
529 * @return const TDesC & A reference to a Descriptor containing the fixed
530 * sequence name indexed by aSequenceNumber.
532 const TDesC& FixedSequenceName(TInt aSequenceNumber);
535 * Returns a list of the supported input datatypes that can be sent to
536 * DevSound for playing audio. The datatypes returned are those that the
537 * DevSound supports given the priority settings passed in
538 * aPrioritySettings. Note that if no supported data types are found this
539 * does not constitute failure, the function will return normally with no
540 * entries in aSupportedDataTypes.
543 * @param RArray< TFourCC > &aSupportedDataTypes The array of supported
544 * data types that will be filled in by this function. The
545 * supported data types of the DevSound are in the form of an
546 * array of TFourCC codes. Any existing entries in the array will
547 * be overwritten on calling this function. If no supported data
548 * types are found given the priority settings, then the
549 * aSupportedDatatypes array will have zero entries.
550 * @param const TMMFPrioritySettings &aPrioritySettings The priority
551 * settings used to determine the supported datatypes. Note this
552 * does not set the priority settings. For input datatypes the
553 * iState member of the priority settings would be expected to be
554 * either EMMFStatePlaying or EMMFStatePlayingRecording. The
555 * priority settings may effect the supported datatypes depending
556 * on the audio routing.
559 void GetSupportedInputDataTypesL(RArray<TFourCC>& aSupportedDataTypesconst,
560 const TMMFPrioritySettings& aPrioritySettings) const;
563 * Returns a list of the supported output dataypes that can be received
564 * from DevSound for recording audio. The datatypes returned are those
565 * that the DevSound supports given the priority settings passed in
566 * aPrioritySettings. Note that if no supported data types are found this
567 * does not constitute failure, the function will return normally with no
568 * entries in aSupportedDataTypes.
571 * @param RArray< TFourCC > &aSupportedDataTypes The array of supported
572 * data types that will be filled in by this function. The
573 * supported datatypes of the DevSound are in the form of an array
574 * of TFourCC codes. Any existing entries in the array will be
575 * overwritten on calling this function. If no supported datatypes
576 * are found given the priority settings, then the
577 * aSupportedDatatypes array will have zero entries.
578 * @param const TMMFPrioritySettings &aPrioritySettings The priority
579 * settings used to determine the supported data types. Note this
580 * does not set the priority settings. For output data types the
581 * iState member of the priority settings would expected to be
582 * either EMMFStateRecording or EMMFStatePlayingRecording. The
583 * priority settings may effect the supported datatypes depending
584 * on the audio routing.
587 void GetSupportedOutputDataTypesL(RArray<TFourCC>& aSupportedDataTypes,
588 const TMMFPrioritySettings& aPrioritySettings) const;
591 * Sets client configuration
593 * @param aActualProcessId the effective devsound client (supplied with SetClientThreadInfo)
594 * @param aProcessId the client of DevSound
595 * @return KErrNone if successful, system wide error otherwise
597 TInt SetClientConfig(const TProcessId& aProcessId);
598 TInt SetClientConfig(const TProcessId& aActualProcessId, const TProcessId& aProcessId);
601 * Return to idle state, preparing for destruction.
605 TBool CloseDevSound();
608 * Called when a ProcessingFinished callback is received
609 * @param aAsyncCompletion Returns ETrue to say the call is asynchronous, with result sent
610 * to AsynchronousOperationComplete()
611 * @return an error code KErrNone if successful
613 TInt ProcessingFinishedReceived(TBool& aAyncCompletion);
615 TInt ProcessingError(TBool& aAyncCompletion);
617 * Empties the buffers below DevSound without deleting the codec
619 * @return KErrNone if successful, otherwise system-wide error code.
623 //provides interface for register a notification event
624 TInt RegisterAsClient(TUid aEventType, const TDesC8& aNotificationRegistrationData = KNullDesC8);
625 //provides interface to cancel the registered notification
626 TInt CancelRegisterAsClient(TUid aEventType);
627 //Gets the notification data for client to resume
628 TInt GetResourceNotificationData(TUid aEventType, TDes8& aNotificationData);
629 //waits for the client to resume playback even after the timeout expires
630 TInt WillResumePlay();
633 * Gets the current play time from the audio renderer
635 * @param TTimeIntervalMicroSeconds& aTime On return contains the current play time
636 * @return an error code KErrNone if successful
638 TInt GetTimePlayed(TTimeIntervalMicroSeconds& aTime);
641 * Queries if the low layers does support resume operation.
643 * @return TBool ETrue if Resume is supported
646 TBool IsResumeSupported();
649 * Resume the operation (Play, Record, TonePlay) temporarily paused .
651 * @return TInt KErrNone if succesful
652 * KErrNotSupported if the operation is not supported by this implementation
657 Used to send a stop call when there is a error in the buffer
659 void BufferErrorEvent();
662 * Used rollback the adapror active state to the previous state prior a Commit call
665 void RollbackAdaptorActiveStateToBeforeCommit();
669 CBody(MDevSoundAdaptationObserver& aDevSoundObserver,
670 MGlobalProperties& aGlobalProperties);
672 void ConstructL(MGlobalProperties& aGlobalProperties);
677 * pointer to devsound framework for callbacks
680 MDevSoundAdaptationObserver& iDevSoundObserver;
683 * holds mode for which current instance is initialized for
688 * holds format for which current instance is initialized for
693 * holds information of supported configurations
694 * (channels, sampling rates, buffersize...)
696 TMMFCapabilities iMmfCapabilities;
699 * holds information of current device configuration
700 * (channels, sampling rates, buffersize...)
702 TMMFCapabilities iMmfConfig;
705 * holds client audio type information
707 TMMFPrioritySettings iPrioritySettings;
710 * pointer to devaudio
713 CDevAudio *iDevAudio;
717 // Pointer to global properties
719 MGlobalProperties* iGlobalProperties;
722 #endif // MMFDEVSOUNDADAPTATIONBODY_H