1 /*

     2 * Copyright (c) 2006-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:  Base class for TTS Utility API

    15 *

    16 */

    17 

    18 

    19 #ifndef NSSTTSUTILITYBASE_H

    20 #define NSSTTSUTILITYBASE_H

    21 

    22 // INCLUDES

    23 #include <mdaaudiosampleplayer.h>

    24 #include <nssttscommon.h>

    25 #include <nssttsutilityobserver.h>

    26 

    27 // CLASS DECLARATION

    28 

    29 /**

    30 * Tts Utility interface.  

    31 *

    32 * @since 3.1

    33 */

    34 class MTtsUtilityBase

    35     {

    36     public: // New functions

    37         

    38         /**

    39         * 2nd phase constructor which can be called from outside.

    40         * 

    41         * @since 3.1

    42         * @param "const MTtsClientUtilityObserver& aObserver" Observer reference.

    43         */

    44         virtual void CreateInstanceSecondPhaseL( MTtsClientUtilityObserver& aObserver ) = 0;   

    45         

    46         /**

    47         * Destructor. Defined here so that client can use M-class pointer to destroy

    48         * the concrete C-object

    49         */                                         

    50         virtual ~MTtsUtilityBase() {};        

    51         

    52         /**

    53         * Opens connection to a specific plugin.

    54         *

    55         * @param "TUid aUid" Plugin UID which will be instantiated

    56         * @since 3.2        

    57         */

    58         virtual void OpenPluginL( TUid aUid ) = 0;

    59         

    60         /**

    61         * Lists UIDs of available Text-To-Speech plugins.

    62         *

    63         * @param "RArray<TUid>& aUids" Output parameter which will contain the

    64         *                              list of plugin UIDs after function call.

    65         * @since 3.2         

    66         */

    67         virtual void ListPluginsL( RArray<TUid>& aUids ) = 0;              

    68                        

    69         /**

    70         * Sets the default style parameters for synthesis.

    71         *

    72         * @param "const TTtsStyle& aStyle" Style created by the client

    73         * @since 3.2        

    74         */

    75         virtual void SetDefaultStyleL( const TTtsStyle& aStyle ) = 0;

    76         

    77         /**

    78         * Returns the registered default style

    79         *

    80         * @return Style reference

    81         * @leave KErrNotReady if no plugin is loaded to handle the function call

    82         * @since 3.2             

    83         */

    84         virtual TTtsStyle& DefaultStyleL() = 0;

    85         

    86         /**

    87         * Sets the speaking rate of synthesizer.

    88         *

    89         * @param TInt aRate Speaking rate value

    90         * @leave KErrNotSupported if synthesizer does not support speaking rate setting

    91         * @since 3.2        

    92         */        

    93         virtual void SetSpeakingRateL( TInt aRate ) = 0;

    94         

    95         /**

    96         * Returns the current speaking rate value.

    97         *

    98         * @return Speaking rate value

    99         * @leave KErrNotSupported if synthesizer does not support speaking rate setting

   100         * @leave KErrNotReady if no plugin is loaded to handle the function call

   101         * @since 3.2        

   102         */

   103         virtual TInt SpeakingRateL() = 0;

   104        

   105         /**

   106         * Open a descriptor ready for playback

   107         *

   108         * @param "const TDesC& aDescriptor" Descriptor containing the text to be synthesized.

   109         * @since 3.2        

   110         */

   111         virtual void OpenDesL( const TDesC& aDescriptor ) = 0; 

   112 

   113         /**

   114         * Opens a descriptor and plays it.

   115         *

   116         * @param "const TDesC& aDescriptor" Descriptor to play 

   117         * @since 3.2        

   118         */

   119         virtual void OpenAndPlayDesL( const TDesC& aDescriptor ) = 0;    

   120         

   121         /**

   122         * Returns the list of supported languages.

   123         * 

   124         * @param "RArray<TLanguage>& aLanguages" Output parameter which contains the languages

   125         * @leave KErrNotReady if no plugin is loaded to handle the function call

   126         * @since 3.2        

   127         */

   128         virtual void GetSupportedLanguagesL( RArray<TLanguage>& aLanguages ) = 0;

   129         

   130         /**

   131         * Returns the list of supported voices for a certain language.

   132         * 

   133         * @param "TLanguage aLanguage" Language

   134         * @param "RArray<TTtsStyle>& aVoices" Output parameter which contains the voices

   135         * @leave KErrNotReady if no plugin is loaded to handle the function call

   136         * @since 3.2

   137         */        

   138         virtual void GetSupportedVoicesL( TLanguage aLanguage, RArray<TTtsStyle>& aVoices ) = 0;        

   139         

   140         /**

   141         * Sets data sink to be a file for the next synthesis event

   142         *

   143         * @param "RFile& aFile" Open file handle where the output is written

   144         * @leave KErrNotReady if no plugin is loaded to handle the function call

   145         * @since 3.2

   146         */

   147         virtual void SetOutputFileL( const RFile& aFile ) = 0; 

   148         

   149         /**

   150         * Adds new style to style collection.

   151         *

   152         * @since 3.1

   153         * @param "TTtsStyle& aStyle" Reference to style.

   154         * @return Assigned style ID.

   155         */

   156         virtual TTtsStyleID AddStyleL( const TTtsStyle& aStyle ) = 0;

   157 

   158         /**

   159         * Deletes style from the style collection.

   160         *

   161         * @since 3.1

   162         * @param "TTtsStyle& aStyle" Reference to style.

   163         * @return Error code.

   164         */

   165         virtual TInt DeleteStyle( TTtsStyleID aID ) = 0;

   166 

   167         /**

   168         * Returns number of styles.

   169         *

   170         * @since 3.1

   171         * @return Number of styles.

   172         */

   173         virtual TUint16 NumberOfStyles() = 0;

   174 

   175         /**

   176         * Returns style based on style ID

   177         *

   178         * @since 3.1

   179         * @param "TTtsStyleID aStyleID" Style identifier.

   180         * @return Reference to found style.

   181         */

   182         virtual TTtsStyle& StyleL( TTtsStyleID aStyleID ) = 0;

   183 

   184         /**

   185         * Returns style based on index.

   186         *

   187         * @since 3.1

   188         * @param "TUint16 aIndex" Index.

   189         * @return Reference to found style.

   190         */

   191         virtual TTtsStyle& StyleL( TUint16 aIndex ) = 0;

   192 

   193         /**

   194         * Begins playback of the initialised audio sample at the current volume

   195         * and priority levels.

   196         *

   197         * When playing of the audio sample is complete, successfully or

   198         * otherwise, the callback function

   199         * <code>MMdaAudioPlayerCallback::MapcPlayComplete()</code> is

   200         * called. This function raises a CMdaAudioPlayerUtility 1 panic if the

   201         * audio player utility is not initialised.

   202         *

   203         * @since 3.1

   204         */

   205         virtual void Play() = 0;

   206 

   207         /**

   208         * Stops playback of the audio sample as soon as possible.

   209         *

   210         * If the audio sample is playing, playback is stopped as soon as

   211         * possible. If playback is already complete, nothing further happens as

   212         * a result of calling this function. The callback function

   213         * <code>MMdaAudioPlayerCallback::MapcPlayComplete()</code> is not

   214         * called.The function raises a CMdaAudioPlayerUtility 1 panic if the

   215         * audio player utility is not initialised.

   216         *

   217         * @since 3.1

   218         */

   219         virtual void Stop() = 0;

   220         

   221         /**

   222         * Changes the current playback volume to a specified value.

   223         *

   224         * The volume can be changed before or during playback and is effective

   225         * immediately. The function raises a CMdaAudioPlayerUtility 1 panic if

   226         * the audio player utility is not initialised.

   227         *

   228         * @since 3.1

   229         * @param	"TInt aVolume"

   230         *          The volume setting. This can be any value from zero to

   231         *          the value returned by a call to

   232         *          <code>CMdaAudioPlayerUtility::MaxVolume()</code>.

   233         *          Setting a zero value mutes the sound. Setting the

   234         *          maximum value results in the loudest possible sound.

   235         */

   236         virtual void SetVolume( TInt aVolume ) = 0;

   237         

   238         /**

   239         * Sets the number of times the audio sample is to be repeated during the

   240         * playback operation.

   241         *

   242         * A period of silence can follow each playing of the sample. The audio

   243         * sample can be repeated indefinitely.

   244         *

   245         * @since 3.1

   246         * @param	"TInt aRepeatNumberOfTimes"

   247         *          The number of times the audio sample, together with

   248         *          the trailing silence, is to be repeated. If this is

   249         *          set to <code>KMdaRepeatForever</code>, then the audio

   250         *          sample, together with the trailing silence, is

   251         *          repeated indefinitely or until <code>Stop()</code> is

   252         *          called. If this is set to zero, then the audio sample

   253         *          is not repeated.

   254         * @param   "const TTimeIntervalMicroSeconds& aTrailingSilence"

   255         *          The time interval of the trailing silence.

   256         */

   257         virtual void SetRepeats( TInt aRepeatNumberOfTimes, 

   258                                  const TTimeIntervalMicroSeconds& aTrailingSilence ) = 0;

   259         

   260         /**

   261         * Returns the duration of the audio sample.

   262         *

   263         * The function raises a CMdaAudioPlayerUtility 1 panic if the audio

   264         * player utility is not initialised.

   265         *

   266         * @since 3.1

   267         * @returns "TTimeIntervalMicroSeconds&"

   268         *          The duration in microseconds

   269         */

   270         virtual const TTimeIntervalMicroSeconds& Duration() = 0;

   271         

   272         /**

   273         * Returns an integer representing the maximum volume.

   274         *

   275         * This is the maximum value which can be passed to

   276         * <code>CMdaAudioPlayerUtility::SetVolume()</code>. The function raises a

   277         * CMdaAudioPlayerUtility 1 panic if the audio player utility is not

   278         * initialised.

   279         *

   280         * @since 3.1

   281         * @returns "TInt"

   282         *          The maximum volume. This value is platform dependent

   283         *          but is always greater than or equal to one.

   284         */

   285         virtual TInt MaxVolume() = 0;

   286         

   287         /**

   288         * Opens a descriptor source and plays it.

   289         *

   290         * @since 3.1

   291         * @param "TDesC8& aDescriptor" Descriptor to play.

   292         */

   293         virtual void OpenAndPlayDesL( const TDesC8& aDescriptor ) = 0;

   294 

   295         /**

   296         * Opens a file source and plays it.

   297         *

   298         * @since 3.1

   299         * @param "TDesC& aFileName" File to play.

   300         */

   301         virtual void OpenAndPlayFileL( const TDesC& aFileName ) = 0;

   302 

   303         /**

   304         * Opens a parsed text source and plays it.

   305         *

   306         * @since 3.1

   307         * @param "CTtsParsedText& aText" Parsed text object to play.

   308         */

   309         virtual void OpenAndPlayParsedTextL( CTtsParsedText& aText ) = 0;

   310 

   311         /**

   312         * Open a clip from a file

   313         *

   314         * @since 3.1

   315         * @param	"const TDesC& aFileName" 

   316         *			File to open

   317         * @leave	Leaves with one of the system wide error codes if a problem is encountered

   318         *			opening the file

   319         */

   320         virtual void OpenFileL( const TDesC& aFileName ) = 0;

   321 

   322         /**

   323         * Open a clip from a descriptor

   324         *

   325         * @since 3.1

   326         * @param	"const TDesC8& aDescriptor" 

   327         *			Descriptor containing audio clip

   328         * @leave	Leaves with one of the system wide error codes if a problem is encountered

   329         *			opening the file

   330         */

   331         virtual void OpenDesL( const TDesC8& aDescriptor ) = 0;

   332 

   333         /**

   334         * Open parsed text source.

   335         *

   336         * @since 3.1

   337         * @param "CTtsParsedText& aText" Reference to parsed text object.

   338         */

   339         virtual void OpenParsedTextL( CTtsParsedText& aText ) = 0;

   340 

   341         /**

   342         * Pauses playback of the audio clip

   343         *

   344         * @since 3.1

   345         * @returns One of the system-wide error codes

   346         */

   347         virtual TInt Pause() = 0;

   348         

   349         /**

   350         * Closes the current audio clip (allowing another clip to be opened)

   351         *

   352         * @since 3.1

   353         */

   354         virtual void Close() = 0;

   355         

   356         /**

   357         * Returns the current playback position in microseconds

   358         *

   359         * @since 3.1

   360         * @retval "TTimeIntervalMicroSeconds& aPosition"

   361         *          The current time position in microseconds from the start of the file

   362         * @returns One of the global error codes

   363         */

   364         virtual TInt GetPosition( TTimeIntervalMicroSeconds& aPosition ) = 0;

   365         

   366         /**

   367         * Returns the current playback position in word index.

   368         *

   369         * @since 3.1

   370         * @retval "TInt& aWordIndex" The current position in words.

   371         * @return Error code.

   372         */

   373         virtual TInt GetPosition( TInt& aWordIndex ) = 0;

   374 

   375         /**

   376         * Set the current playback position in microseconds from the start of the file

   377         *

   378         * @since 3.1

   379         * @param "TTimeIntervalMicroSeconds& aPosition"

   380         *          The position to move to in microseconds past the start of the file

   381         */

   382         virtual void SetPosition( const TTimeIntervalMicroSeconds& aPosition ) = 0;

   383         

   384         /**

   385         * Set the current playback position in word index.

   386         *

   387         * @since 3.1

   388         * @param "TInt aWordIndex" Playback position.

   389         */

   390         virtual void SetPosition( TInt aWordIndex ) = 0;

   391 

   392         /**

   393         *

   394         * Set the priority for playback. This is used to arbitrate between multiple 

   395         * objects trying to access a single sound device

   396         *

   397         * @since 3.1

   398         * @param "TInt aPriority"

   399         * @param "TMdaPriorityPreference aPref"

   400         *         Quality/time preference tradeoff

   401         * 

   402         * @returns "TInt" One of the global error codes

   403         */

   404         virtual TInt SetPriority( TInt aPriority, TMdaPriorityPreference aPref ) = 0;

   405         

   406         /**

   407         * Returns the current playback volume

   408         *

   409         * @since 3.1

   410         * @retval "TInt& aVolume"

   411         *          A volume value between 0 and the value returned by <code>MaxVolume()</code>

   412         * @returns "TInt" One of the global error codes

   413         */

   414         virtual TInt GetVolume( TInt& aVolume ) = 0;

   415         

   416         /**

   417         * Sets the current playback balance

   418         *

   419         * @since 3.1

   420         * @param "TInt& aBalance"

   421         *        A value between <code>KMMFBalanceMaxLeft</code> 

   422         *        and <code>KMMFBalanceMaxRight</code>. The default value is 

   423         *        <code>KMMFBalanceCenter</code>

   424         * @returns "TInt" One of the global error codes

   425         */

   426         virtual TInt SetBalance( TInt aBalance = KMMFBalanceCenter ) = 0;

   427         

   428         /**

   429         * Returns the current playback balance

   430         *

   431         * @since 3.1

   432         * @retval "TInt& aBalance"

   433         *         A value between <code>KMMFBalanceMaxLeft</code> 

   434         *         and <code>KMMFBalanceMaxRight</code>

   435         * @returns "TInt" One of the global error codes

   436         */

   437         virtual TInt GetBalance( TInt& aBalance ) = 0;

   438         

   439         /**

   440         * Send a synchronous custom command to the controller

   441         *

   442         * @since 3.1

   443         * @param "aDestination"	"The destination of the message, consisting of the uid of

   444         *        the interface of this message."

   445         * @param "aFunction" "The function number to indicate which function is to be called

   446         *        on the interface defined in the aDestination parameter."

   447         * @param "aDataTo1" "A reference to the first chunk of data to be copied to the controller 

   448         *        framework. The exact contents of the data are dependent on the 

   449         *        interface being called.  Can be KNullDesC8."

   450         * @param "aDataTo2" "A reference to the second chunk of data to be copied to the controller 

   451         *        framework. The exact contents of the data are dependent on the 

   452         *        interface being called.  Can be KNullDesC8."

   453         * @param "aDataFrom" "A reference to an area of memory to which the controller framework will 

   454         *        write any data to be passed back to the client.  Can't be KNullDesC8."

   455         * @return "The result of the request. Exact range of values is dependent on the interface."

   456         */

   457         virtual TInt CustomCommandSync( const TMMFMessageDestinationPckg& aDestination, 

   458                                         TInt aFunction, 

   459                                         const TDesC8& aDataTo1, 

   460                                         const TDesC8& aDataTo2, 

   461                                         TDes8& aDataFrom) = 0;

   462         /**

   463         * Send a synchronous custom command to the controller

   464         *

   465         * @since 3.1

   466         * @param "aDestination" "The destination of the message, consisting of the uid of

   467         *		 the interface of this message."

   468         * @param "aFunction" "The function number to indicate which function is to be called

   469         *        on the interface defined in the aDestination parameter."

   470         * @param "aDataTo1" "A reference to the first chunk of data to be copied to the controller 

   471         *         framework. The exact contents of the data are dependent on the 

   472         *         interface being called.  Can be KNullDesC8."

   473         * @param "aDataTo2" "A reference to the second chunk of data to be copied to the controller 

   474         *         framework. The exact contents of the data are dependent on the 

   475         *         interface being called.  Can be KNullDesC8."

   476         * @return "The result of the request. Exact range of values is dependent on the interface."

   477         */

   478         virtual TInt CustomCommandSync( const TMMFMessageDestinationPckg& aDestination, 

   479                                         TInt aFunction, 

   480                                         const TDesC8& aDataTo1, 

   481                                         const TDesC8& aDataTo2 ) = 0;

   482         /**

   483         * Send a asynchronous custom command to the controller

   484         * Note: This method will return immediately.  The RunL of the active object owning the 

   485         * <code>aStatus<\code> parameter will be called when the command is completed by the 

   486         * controller framework.

   487         *

   488         * @since 3.1

   489         * @param "aDestination" "The destination of the message, consisting of the uid of

   490         *        the interface of this message."

   491         * @param "aFunction" "The function number to indicate which function is to be called

   492         *        on the interface defined in the aDestination parameter."

   493         * @param "aDataTo1" "A reference to the first chunk of data to be copied to the controller 

   494         *        framework. The exact contents of the data are dependent on the 

   495         *        interface being called.  Can be KNullDesC8."

   496         * @param "aDataTo2" "A reference to the second chunk of data to be copied to the controller 

   497         *        framework. The exact contents of the data are dependent on the 

   498         *        interface being called.  Can be KNullDesC8."

   499         * @param "aDataFrom" "A reference to an area of memory to which the controller framework will 

   500         *        write any data to be passed back to the client.  Can't be KNullDesC8."

   501         * @param "aStatus" "The TRequestStatus of an active object.  This will contain the 

   502         *        result of the request on completion.  The exact range of 

   503         *        result values is dependent on the interface."

   504         */

   505         virtual void CustomCommandAsync( const TMMFMessageDestinationPckg& aDestination,  

   506                                          TInt aFunction, 

   507                                          const TDesC8& aDataTo1, 

   508                                          const TDesC8& aDataTo2, 

   509                                          TDes8& aDataFrom, 

   510                                          TRequestStatus& aStatus ) = 0;

   511         /**

   512         * Send a asynchronous custom command to the controller

   513         * Note: This method will return immediately.  The RunL of the active object owning the 

   514         * <code>aStatus<\code> parameter will be called when the command is completed by the 

   515         * controller framework.

   516         *

   517         * @since 3.1

   518         * @param "aDestination" "The destination of the message, consisting of the uid of

   519         *        the interface of this message."

   520         * @param "aFunction" "The function number to indicate which function is to be called

   521         *        on the interface defined in the aDestination parameter."

   522         * @param "aDataTo1" "A reference to the first chunk of data to be copied to the controller 

   523         *        framework. The exact contents of the data are dependent on the 

   524         *        interface being called.  Can be KNullDesC8."

   525         * @param "aDataTo2" "A reference to the second chunk of data to be copied to the controller 

   526         *        framework. The exact contents of the data are dependent on the 

   527         *        interface being called.  Can be KNullDesC8."

   528         * @param "aStatus" "The TRequestStatus of an active object.  This will contain the 

   529         *        result of the request on completion.  The exact range of 

   530         *        result values is dependent on the interface."

   531         */

   532         virtual void CustomCommandAsync( const TMMFMessageDestinationPckg& aDestination, 

   533                                          TInt aFunction, 

   534                                          const TDesC8& aDataTo1, 

   535                                          const TDesC8& aDataTo2, 

   536                                          TRequestStatus& aStatus ) = 0;

   537     };

   538 

   539 #endif // NSSTTSUTILITYBASE_H   

   540 

   541 // End of File