1 /*

     2 * Copyright (c) 2004-2007 Nokia Corporation and/or its subsidiary(-ies). 

     3 * All rights reserved.

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

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description:  Audio interface for DevTts

    15 *

    16 */

    17 

    18 

    19 #ifndef DEVTTSAUDIO_H

    20 #define DEVTTSAUDIO_H

    21 

    22 //  INCLUDES

    23 

    24 #include <e32base.h>

    25 #include <sounddevice.h>    // DevSound

    26 #include <nssdevtts.h>      // DevTTS public header

    27 

    28 

    29 // FORWARD DECLARATION

    30 

    31 class CAudioOutput;

    32 

    33 

    34 // CLASS DECLARATIONS

    35 

    36 class MDevTTSAudioObserver

    37     {

    38     public:

    39         

    40         /**

    41         * Notifies the observer that initialization has been completed.

    42         *

    43         * @param "TInt aError"

    44         *        KErrNone if successful, otherwise one of the system level 

    45         *        error codes.

    46         */

    47         virtual void MdtaoInitializeComplete( TInt aError ) = 0;

    48         

    49         /**

    50         * Audio device wants the buffer to be filled. Client should provide

    51         * data to the descriptor given as parameter and call PlayData when

    52         * data is ready to be played.

    53         *

    54         * @param "TDes8& aBuffer"

    55         *        Descriptor which should be filled

    56         * @param "TInt aSizeRequested"

    57         *        Number of bytes requested

    58         */

    59         virtual void MdtaoBufferToBeFilled( TDes8& aBuffer,

    60                                             TInt aSizeRequested ) = 0;

    61         

    62         /**

    63         * Called when playback process is finished, successfully or otherwise.

    64         *

    65         * @param "TInt aError"

    66         *        KErrNone if everything succeeded, one of the system level error

    67         *        codes otherwise.

    68         */

    69         virtual void MdtaoPlayFinished( TInt aError ) = 0;

    70         

    71     };

    72 

    73 /**

    74 * Audio playback functionality for DevTTS.

    75 */

    76 class CDevTTSAudio : public CBase, 

    77                      public MDevSoundObserver

    78     {

    79     public:  // Constructors and destructor

    80         

    81         /**

    82         * Two-phased constructor.

    83         */

    84         static CDevTTSAudio* NewL( MDevTTSAudioObserver& aObserver, 

    85                                    TInt aPriority );

    86         

    87         /**

    88         * Destructor.

    89         */

    90         virtual ~CDevTTSAudio();

    91         

    92     public: // New functions

    93         

    94         /**

    95         * Initializes the audio device. Method is asynchronous.

    96         * MDevTTSAudioObserver::InitializeComplete() called when initialization

    97         * is ready.

    98         */

    99         void InitializeL();

   100         

   101          /**

   102         * Configures the audio device. Method is synchronous.

   103         */

   104         void ConfigL( TUint aSamplingRate, TUint aBitsPerSample, 

   105                       TBool aStereo, TUint aBufferSize );

   106         

   107         /**

   108         * Clears the audio device resources. Counter part of InitializeL.

   109         */

   110         void Clear();

   111         

   112         /**

   113         * Returns the current balance setting.

   114         *

   115         * @return Balance.

   116         */

   117         TInt Balance();

   118 

   119         /**

   120         * Returns maximum volume.

   121         *

   122         * @return Max volume.

   123         */

   124         TInt MaxVolume();

   125 

   126         /**

   127         * Initialises the audio playback process.

   128         */

   129         void PlayInitL();

   130         

   131         /**

   132         * Plays the filled buffer, Should be called when BufferToBeFilled 

   133         * callback has filled the requested buffer.

   134         *

   135         * @param "TBool aLastBuffer"

   136         *        Flag to tell if this is the last buffer

   137         */

   138         void PlayData( TBool aLastBuffer );

   139         

   140         /**

   141         * Sets the priority for audio playback.

   142         * 

   143         * @param "TInt aPriority"

   144         *        Priority value.

   145         * @param "TDevTTSAudioPreference aPref"'

   146         *        Preference setting. Quality, time or both.

   147         */

   148         void SetAudioPriority( TInt aPriority, TDevTTSAudioPreference aPref );

   149 

   150         /**

   151         * Sets the audio output routing

   152         * 

   153         * @param TInt aAudioOutput

   154         *        New output.

   155         */

   156         void SetAudioOutputL( TInt aAudioOutput );

   157 

   158         /**

   159         * Sets the playback balance.

   160         *

   161         * @param "TInt aBalance"

   162         *        Balance value to be set.

   163         */

   164         void SetBalance( TInt aVolume );

   165         

   166         /**

   167         * Sets the playback volume. Range is from 0 (minumum) to MaxVolume().

   168         * Out of range values will be discarded.

   169         *

   170         * @param "TInt aVolume"

   171         *        Volume value to be set, from 0 to MaxVolume.

   172         */

   173         void SetVolume( TInt aVolume );

   174 

   175         /**

   176         * Sets the volume ramp duration

   177         *

   178         * @param "TTimeIntervalMicroSeconds& aRampDuration"

   179         *        Ramp duration.

   180         */

   181         void SetVolumeRamp( const TTimeIntervalMicroSeconds& aRampDuration );

   182         

   183         /**

   184         * Stops the ongoing playback operation.

   185         */

   186         void Stop();

   187         

   188         /**

   189         * Pauses the ongoing playback operation

   190         */

   191         void Pause();

   192         

   193         /**

   194         * Returns the current volume setting.

   195         *

   196         * @return Volume

   197         */

   198         TInt Volume();

   199 

   200     public: // Functions from base classes

   201         

   202         /**

   203         * From MDevSoundObserver::InitializeComplete

   204         * Handles initialization completion event from DevSound.

   205         * Called InitializeL() function completes.

   206         *

   207         * @param "TInt aError"

   208         *        Error code. KErrNone if successful. Other values are possible

   209         *        indicating a problem initializing CMMFDevSound object.

   210         */

   211         void InitializeComplete( TInt aError );

   212         

   213         /**

   214         * From MDevSoundObserver::ToneFinished

   215         * Handles tone play completion event.

   216         * Called when an attempt to play tone has

   217         * completed, successfully or otherwise.

   218         *

   219         * @param "TInt aError"

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

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

   222         *        another higher priority client. KErrCancel playing of the audio

   223         *        sample is stopped by DevSound client another higher priority client.

   224         */

   225         void ToneFinished( TInt aError ); 

   226         

   227         /**

   228         * From MDevSoundObserver::BufferToBeFilled

   229         * Handles CMMFDevSound object's data request event.

   230         * CMMFDevSound object calls this method when and where it needs data for

   231         * playing or converting. The observer should notify CMMFDevSound object as

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

   233         * PlayData(), otherwise the implementation might callback method PlayError()

   234         * on derived class object with error code KErrUnderflow.

   235         *

   236         * @param "CMMFBuffer* aBuffer"

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

   238         *         needed is specified in CMMFBuffer::RequestSize().

   239         */

   240         void BufferToBeFilled( CMMFBuffer* aBuffer );

   241         

   242         /**

   243         * From MDevSoundObserver::PlayError

   244         * Handles play completion or cancel event.

   245         * Called when an attempt to play audio sample

   246         * has completed, successfully or otherwise.

   247         *

   248         * @param "TInt aError"

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

   250         *        audio sample is complete. KErrAccessDenied the sound device is in

   251         *        use by another higher priority client.

   252         */

   253         void PlayError( TInt aError ); 

   254         

   255         /**

   256         * From MDevSoundObserver::BufferToBeEmptied

   257         * Handles CMMFDevSound object's data request event.

   258         * Called when the buffer, aBuffer gets filled

   259         * while recording or converting. The observer should notify CMMFDevSound

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

   261         * calling RecordData(), otherwise the implementation might callback

   262         * method RecordError() on derived class object with error code KErrOverflow.

   263         *

   264         * @param "CMMFBuffer* aBuffer"

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

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

   267         */

   268         void BufferToBeEmptied( CMMFBuffer* aBuffer ); 

   269         

   270         /**

   271         * From MDevSoundObserver::RecordError

   272         * Handles record completion or cancel event.

   273         * Called when an attempt to record audio sample

   274         * has completed, successfully or otherwise.

   275         *

   276         * @param "TInt aError"

   277         *        Error code. The status of recording. KErrOverflow audio devices

   278         *        runs out of internal buffer. KErrAccessDenied the sound device is

   279         *        in use by another higher priority client.

   280         */

   281         void RecordError( TInt aError ); 

   282         

   283         /**

   284         * From MDevSoundObserver::ConvertError

   285         * Handles conversion completion or cancel event.

   286         * Called when an attempt to convert data from

   287         * source format to destination format has completed, 

   288         * successfully or otherwise.

   289         *

   290         * @param	"TInt aError"

   291         *           Error code. KErrCancel conversion operation is cancelled. KErrNone

   292         *           conversion is complete. Other values are possible indicating a

   293         *           problem converting data.

   294         */

   295         void ConvertError( TInt aError );

   296         

   297         /**

   298         * From MDevSoundObserver::DeviceMessage

   299         * Handles device event.

   300         * Called when a message is received from the

   301         * audio hardware device.

   302         *

   303         * @param "aMessageType" 

   304         *         Defines the type of message. Used to determine how to 

   305         *         interpret the contents of aMsg.

   306         * @param "aMsg"

   307         *         Message that is packed in the Descriptor format.

   308         */

   309         void DeviceMessage( TUid aMessageType, const TDesC8& aMsg );

   310         

   311         /**

   312         * From MDevSoundObserver::SendEventToClient

   313         * Handles policy request completion event.

   314         * Called when an attempt to acquire sound

   315         * device is rejected by audio policy server.

   316         *

   317         * @param "const TMMFEvent& aEvent"

   318         */

   319         void SendEventToClient( const TMMFEvent& aEvent );  

   320         

   321     private:

   322         

   323         /**

   324         * C++ default constructor.

   325         */

   326         CDevTTSAudio( MDevTTSAudioObserver& aObserver, TInt aPriority );

   327         

   328         /**

   329         * By default Symbian 2nd phase constructor is private.

   330         */

   331         void ConstructL();

   332         

   333     private:    // Data

   334     

   335         // Observer

   336         MDevTTSAudioObserver& iObserver;

   337         

   338         // DevSound

   339         CMMFDevSound* iDevsound;

   340         

   341         // Used for setting audio routing

   342         CAudioOutput* iAudioOutput;

   343         

   344         // DevSound capabilities

   345         TMMFCapabilities iDevCap;

   346         

   347         // Buffer which is being filled

   348         CMMFBuffer* iBuffer;

   349 

   350         // Numerical value of the priority setting

   351         TInt iPriority;

   352         

   353         // DevSound priority settings

   354         TMMFPrioritySettings iAudioPriority;

   355 

   356         // Current balance

   357         TInt iBalance;

   358 

   359         // Current volume

   360         TInt iVolume;

   361     };

   362     

   363 #endif // DEVTTSAUDIO_H

   364     

   365 // End of File