diff -r cad71a31b7fc -r e36f3802f733 srsf/ttsutility/src/ttsutilitybody.h --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/srsf/ttsutility/src/ttsutilitybody.h Wed Sep 01 12:29:17 2010 +0100 @@ -0,0 +1,666 @@ +/* +* Copyright (c) 2004-2007 Nokia Corporation and/or its subsidiary(-ies). +* All rights reserved. +* This component and the accompanying materials are made available +* under the terms of "Eclipse Public License v1.0" +* which accompanies this distribution, and is available +* at the URL "http://www.eclipse.org/legal/epl-v10.html". +* +* Initial Contributors: +* Nokia Corporation - initial contribution. +* +* Contributors: +* +* Description: Body behind TTS Utility API +* +*/ + + +#ifndef TTSUTILITYBODY_H +#define TTSUTILITYBODY_H + +// INCLUDES +#include +#include +#include +#include "srsfbldvariant.hrh" + +// CLASS DECLARATION + +/** +* Implementation for TTS Utility API. +* +* @lib TtsUtility.lib +* @since 2.8 +*/ +NONSHARABLE_CLASS( CTtsUtilityBody ) : public CBase, + public MMdaAudioPlayerCallback, + public MMMFControllerEventMonitorObserver + { + public: // Constructors and destructor + + /** + * Two-phased constructor. + */ + static CTtsUtilityBody* NewL( MTtsClientUtilityObserver& aObserver ); + + /** + * Destructor. + */ + virtual ~CTtsUtilityBody(); + + public: // New functions + + + /** + * Opens connection to a specific plugin. + * + * @param "TUid aUid" Plugin UID which will be instantiated + */ + void OpenPluginL( TUid aUid ); + + /** + * Lists UIDs of available Text-To-Speech plugins. + * + * @param "RArray& aUids" Output parameter which will contain the + * list of plugin UIDs after function call. + */ + void ListPluginsL( RArray& aUids ); + + /** + * Sets the default style parameters for synthesis. + * + * @param "const TTtsStyle& aStyle" Style created by the client + */ + void SetDefaultStyleL( const TTtsStyle& aStyle ); + + /** + * Returns the registered default style + * + * @return Style reference + * @leave KErrNotReady if no plugin is loaded to handle the function call + */ + TTtsStyle& DefaultStyleL(); + + /** + * Sets the speaking rate of synthesizer. + * + * @param TInt aRate Speaking rate value + * @leave KErrNotSupported if synthesizer does not support speaking rate setting + */ + void SetSpeakingRateL( TInt aRate ); + + /** + * Returns the current speaking rate value. + * + * @return Speaking rate value + * @leave KErrNotSupported if synthesizer does not support speaking rate setting + * @leave KErrNotReady if no plugin is loaded to handle the function call + */ + TInt SpeakingRateL(); + + /** + * Returns the list of supported languages. + * + * @param "RArray& aLanguages" Output parameter which contains the languages + * @leave KErrNotReady if no plugin is loaded to handle the function call + */ + void GetSupportedLanguagesL( RArray& aLanguages ); + + /** + * Returns the list of supported voices for a certain language. + * + * @param "TLanguage aLanguage" Language + * @param "RArray& aVoices" Output parameter which contains the voices + * @leave KErrNotReady if no plugin is loaded to handle the function call + */ + void GetSupportedVoicesL( TLanguage aLanguage, RArray& aVoices ); + + /** + * Open a descriptor ready for playback + * + * @param "const TDesC& aDescriptor" Descriptor containing the text to be synthesized. + * @since 3.2 + */ + void OpenDesL( const TDesC& aDescriptor ); + + /** + * Opens a descriptor and plays it. + * + * @param "const TDesC& aDescriptor" Descriptor to play + * @since 3.2 + */ + void OpenAndPlayDesL( const TDesC& aDescriptor ); + + /** + * Directing output of a next synthesis to the specified file + * + * @param "RFile& aFile" Open file handle to save output of next synthesis. + * @since 3.2 + */ + void SetOutputFileL( const RFile& aFile ); + + /** + * Adds new style to style collection. + * + * @param "TTtsStyle& aStyle" Reference to style. + * @return Assigned style ID. + */ + TTtsStyleID AddStyleL( const TTtsStyle& aStyle ); + + /** + * Deletes style from the style collection. + * + * @param "TTtsStyle& aStyle" Reference to style. + * @return Error code. + */ + TInt DeleteStyle( TTtsStyleID aID ); + + /** + * Returns number of styles. + * + * @return Number of styles. + */ + TUint16 NumberOfStyles(); + + /** + * Returns style based on style ID + * + * @param "TTtsStyleID aStyleID" Style identifier. + * @return Reference to found style. + */ + TTtsStyle& StyleL( TTtsStyleID aStyleID ); + + /** + * Returns style based on index. + * + * @param "TUint16 aIndex" Index. + * @return Reference to found style. + */ + TTtsStyle& StyleL( TUint16 aIndex ); + + /** + * Begins playback of the initialised audio sample at the current volume + * and priority levels. + * + * When playing of the audio sample is complete, successfully or + * otherwise, the callback function + * MMdaAudioPlayerCallback::MapcPlayComplete() is + * called. This function raises a CMdaAudioPlayerUtility 1 panic if the + * audio player utility is not initialised. + */ + void Play(); + + /** + * Stops playback of the audio sample as soon as possible. + * + * If the audio sample is playing, playback is stopped as soon as + * possible. If playback is already complete, nothing further happens as + * a result of calling this function. The callback function + * MMdaAudioPlayerCallback::MapcPlayComplete() is not + * called.The function raises a CMdaAudioPlayerUtility 1 panic if the + * audio player utility is not initialised. + */ + void Stop(); + + /** + * Changes the current playback volume to a specified value. + * + * The volume can be changed before or during playback and is effective + * immediately. The function raises a CMdaAudioPlayerUtility 1 panic if + * the audio player utility is not initialised. + * + * @param "TInt aVolume" + * The volume setting. This can be any value from zero to + * the value returned by a call to + * CMdaAudioPlayerUtility::MaxVolume(). + * Setting a zero value mutes the sound. Setting the + * maximum value results in the loudest possible sound. + */ + void SetVolume( TInt aVolume ); + + /** + * Sets the number of times the audio sample is to be repeated during the + * playback operation. + * + * A period of silence can follow each playing of the sample. The audio + * sample can be repeated indefinitely. + * + * @param "TInt aRepeatNumberOfTimes" + * The number of times the audio sample, together with + * the trailing silence, is to be repeated. If this is + * set to KMdaRepeatForever, then the audio + * sample, together with the trailing silence, is + * repeated indefinitely or until Stop() is + * called. If this is set to zero, then the audio sample + * is not repeated. + * @param "const TTimeIntervalMicroSeconds& aTrailingSilence" + * The time interval of the trailing silence. + */ + void SetRepeats( TInt aRepeatNumberOfTimes, + const TTimeIntervalMicroSeconds& aTrailingSilence ); + + /** + * Returns the duration of the audio sample. + * + * The function raises a CMdaAudioPlayerUtility 1 panic if the audio + * player utility is not initialised. + * + * @returns "TTimeIntervalMicroSeconds&" + * The duration in microseconds + */ + const TTimeIntervalMicroSeconds& Duration(); + + /** + * Returns an integer representing the maximum volume. + * + * This is the maximum value which can be passed to + * CMdaAudioPlayerUtility::SetVolume(). The function raises a + * CMdaAudioPlayerUtility 1 panic if the audio player utility is not + * initialised. + * + * @returns "TInt" + * The maximum volume. This value is platform dependent + * but is always greater than or equal to one. + */ + TInt MaxVolume(); + + /** + * Opens a descriptor source and plays it. + * + * @param "TDesC8& aDescriptor" Descriptor to play. + */ + void OpenAndPlayDesL( const TDesC8& aDescriptor ); + + /** + * Opens a file source and plays it. + * + * @param "TDesC& aFileName" File to play. + */ + void OpenAndPlayFileL( const TDesC& aFileName ); + + /** + * Opens a parsed text source and plays it. + * + * @param "CTtsParsedText& aText" Parsed text object to play. + */ + void OpenAndPlayParsedTextL( CTtsParsedText& aText ); + + /** + * Open a clip from a file + * + * @param "const TDesC& aFileName" + * File to open + * @leave Leaves with one of the system wide error codes if a problem is encountered + * opening the file + */ + void OpenFileL( const TDesC& aFileName ); + + /** + * Open a clip from a descriptor + * + * @param "const TDesC8& aDescriptor" + * Descriptor containing audio clip + * @leave Leaves with one of the system wide error codes if a problem is encountered + * opening the file + */ + void OpenDesL( const TDesC8& aDescriptor ); + + /** + * Open parsed text source. + * + * @param "CTtsParsedText& aText" Reference to parsed text object. + */ + void OpenParsedTextL( CTtsParsedText& aText ); + + /** + * Pauses playback of the audio clip + * @returns One of the system-wide error codes + */ + TInt Pause(); + + /** + * Closes the current audio clip (allowing another clip to be opened) + */ + void Close(); + + /** + * Returns the current playback position in microseconds + * + * @retval "TTimeIntervalMicroSeconds& aPosition" + * The current time position in microseconds from the start of the file + * @returns One of the global error codes + */ + TInt GetPosition( TTimeIntervalMicroSeconds& aPosition ); + + /** + * Returns the current playback position in word index. + * + * @retval "TInt& aWordIndex" The current position in words. + * @return Error code. + */ + TInt GetPosition( TInt& aWordIndex ); + + /** + * Set the current playback position in microseconds from the start of the file + * + * @param "TTimeIntervalMicroSeconds& aPosition" + * The position to move to in microseconds past the start of the file + */ + void SetPosition( const TTimeIntervalMicroSeconds& aPosition ); + + /** + * Set the current playback position in word index. + * + * @param "TInt aWordIndex" Playback position. + */ + void SetPosition( TInt aWordIndex ); + + /** + * + * Set the priority for playback. This is used to arbitrate between multiple + * objects trying to access a single sound device + * + * @param "TInt aPriority" + * @param "TMdaPriorityPreference aPref" + * Quality/time preference tradeoff + * + * @returns "TInt" One of the global error codes + */ + TInt SetPriority( TInt aPriority, TMdaPriorityPreference aPref ); + + /** + * Returns the current playback volume + * + * @retval "TInt& aVolume" + * A volume value between 0 and the value returned by MaxVolume() + * @returns "TInt" One of the global error codes + */ + TInt GetVolume( TInt& aVolume ); + + /** + * Sets the current playback balance + * + * @param "TInt& aBalance" + * A value between KMMFBalanceMaxLeft + * and KMMFBalanceMaxRight. The default value is + * KMMFBalanceCenter + * @returns "TInt" One of the global error codes + */ + TInt SetBalance( TInt aBalance = KMMFBalanceCenter ); + + /** + * Returns the current playback balance + * + * @retval "TInt& aBalance" + * A value between KMMFBalanceMaxLeft + * and KMMFBalanceMaxRight + * @returns "TInt" One of the global error codes + */ + TInt GetBalance( TInt& aBalance ); + + /** + * Send a synchronous custom command to the controller + * @param "aDestination" "The destination of the message, consisting of the uid of + * the interface of this message." + * @param "aFunction" "The function number to indicate which function is to be called + * on the interface defined in the aDestination parameter." + * @param "aDataTo1" "A reference to the first chunk of data to be copied to the controller + * framework. The exact contents of the data are dependent on the + * interface being called. Can be KNullDesC8." + * @param "aDataTo2" "A reference to the second chunk of data to be copied to the controller + * framework. The exact contents of the data are dependent on the + * interface being called. Can be KNullDesC8." + * @param "aDataFrom" "A reference to an area of memory to which the controller framework will + * write any data to be passed back to the client. Can't be KNullDesC8." + * @return "The result of the request. Exact range of values is dependent on the interface." + */ + TInt CustomCommandSync( const TMMFMessageDestinationPckg& aDestination, + TInt aFunction, + const TDesC8& aDataTo1, + const TDesC8& aDataTo2, + TDes8& aDataFrom); + /** + * Send a synchronous custom command to the controller + * @param "aDestination" "The destination of the message, consisting of the uid of + * the interface of this message." + * @param "aFunction" "The function number to indicate which function is to be called + * on the interface defined in the aDestination parameter." + * @param "aDataTo1" "A reference to the first chunk of data to be copied to the controller + * framework. The exact contents of the data are dependent on the + * interface being called. Can be KNullDesC8." + * @param "aDataTo2" "A reference to the second chunk of data to be copied to the controller + * framework. The exact contents of the data are dependent on the + * interface being called. Can be KNullDesC8." + * @return "The result of the request. Exact range of values is dependent on the interface." + */ + TInt CustomCommandSync( const TMMFMessageDestinationPckg& aDestination, + TInt aFunction, + const TDesC8& aDataTo1, + const TDesC8& aDataTo2 ); + /** + * Send a asynchronous custom command to the controller + * Note: This method will return immediately. The RunL of the active object owning the + * aStatus<\code> parameter will be called when the command is completed by the + * controller framework. + * @param "aDestination" "The destination of the message, consisting of the uid of + * the interface of this message." + * @param "aFunction" "The function number to indicate which function is to be called + * on the interface defined in the aDestination parameter." + * @param "aDataTo1" "A reference to the first chunk of data to be copied to the controller + * framework. The exact contents of the data are dependent on the + * interface being called. Can be KNullDesC8." + * @param "aDataTo2" "A reference to the second chunk of data to be copied to the controller + * framework. The exact contents of the data are dependent on the + * interface being called. Can be KNullDesC8." + * @param "aDataFrom" "A reference to an area of memory to which the controller framework will + * write any data to be passed back to the client. Can't be KNullDesC8." + * @param "aStatus" "The TRequestStatus of an active object. This will contain the + * result of the request on completion. The exact range of + * result values is dependent on the interface." + */ + void CustomCommandAsync( const TMMFMessageDestinationPckg& aDestination, + TInt aFunction, + const TDesC8& aDataTo1, + const TDesC8& aDataTo2, + TDes8& aDataFrom, + TRequestStatus& aStatus ); + /** + * Send a asynchronous custom command to the controller + * Note: This method will return immediately. The RunL of the active object owning the + * aStatus<\code> parameter will be called when the command is completed by the + * controller framework. + * @param "aDestination" "The destination of the message, consisting of the uid of + * the interface of this message." + * @param "aFunction" "The function number to indicate which function is to be called + * on the interface defined in the aDestination parameter." + * @param "aDataTo1" "A reference to the first chunk of data to be copied to the controller + * framework. The exact contents of the data are dependent on the + * interface being called. Can be KNullDesC8." + * @param "aDataTo2" "A reference to the second chunk of data to be copied to the controller + * framework. The exact contents of the data are dependent on the + * interface being called. Can be KNullDesC8." + * @param "aStatus" "The TRequestStatus of an active object. This will contain the + * result of the request on completion. The exact range of + * result values is dependent on the interface." + * @since 7.0s + */ + void CustomCommandAsync( const TMMFMessageDestinationPckg& aDestination, + TInt aFunction, + const TDesC8& aDataTo1, + const TDesC8& aDataTo2, + TRequestStatus& aStatus ); + + public: // Functions from MMdaAudioPlayerCallback + + void MapcInitComplete( TInt /*aError*/, const TTimeIntervalMicroSeconds& /*aDuration*/ ) {} + void MapcPlayComplete( TInt /*aError*/ ) {} + + + public: // Functions from MMMFControllerEventMonitorObserver + + void HandleEvent( const TMMFEvent& aEvent ); + + private: + + /** + * C++ default constructor. + * + * @param "MTtsClientUtilityObserver& aObserver" Reference to observer. + */ + CTtsUtilityBody( MTtsClientUtilityObserver& aObserver ); + + /** + * By default Symbian 2nd phase constructor is private. + */ + void ConstructL(); + + // Prohibit copy constructor if not deriving from CBase. + CTtsUtilityBody( const CTtsUtilityBody& ); + // Prohibit assigment operator if not deriving from CBase. + CTtsUtilityBody& operator=( const CTtsUtilityBody& ); + + /** + * Utility function to open connection to controller plugin. + * + * @param "TUid aPluginUid" Plugin UID + */ + void OpenControllerConnectionL( TUid aPluginUid ); + + /** + * Utility function to copy parsed text structure and convert style ids. + * + * @param "CTtsParsedText& aText" Parsed text which is copied + */ + void CopyParsedTextL( CTtsParsedText& aText ); + + /** + * Checks if there is an existing connection to some controller plugin + * + * @return ETrue if there is an connection + */ + TBool IsPluginOpen(); + + /** + * Stores priority settings but does not send them to the controller + * plugin just yet. + * + * @param "TInt aPriority" Audio priority + * @param "TMdaPriorityPreference aPref" Audio preference + */ + void StorePriority( TInt aPriority, TMdaPriorityPreference aPref ); + + /** + * Handles conversion from unicode to utf-8 + * + * @param "const TDesC& aDes" Unicode descriptor + * @return Pointer to created buffer, pushed to cleanupstack + */ + HBufC8* ConvertToUtf8LC( const TDesC& aDes ); + + /** + * Adds data sink to controller according iUidOfDataSink and iOutputFile. + */ + void AddDataSinkL(); + + /** + * Responds that the correct plugin is loaded + * + * @param "TTtsQuality aQuality" Synthesis quality parameter + * @param "TLanguage aLanguage" Synthesis language + * @param "const TTtsVoice& aVoice" Synthesis voice + */ + void CheckAndLoadCorrectPluginL( TTtsQuality aQuality, TLanguage aLanguage, + const TTtsVoice& aVoice ); + + /** + * Tells if currently loaded plugin can handle synthesis with given parameters + * + * @param "TLanguage aLanguage" Language to be used + * @param "const TTtsVoice& aVoice" Voice to be used + * @return ETrue if parameters are supported + */ + TBool IsSupportedSpeaker( TLanguage aLanguage, const TTtsVoice& aVoice ); + + private: // Data + + // Client side representation of controller plugin in use + RMMFController iController; + + // Audio custom commands + RMMFAudioPlayDeviceCustomCommands iAudioPlayDeviceCommands; + RMMFAudioPlayControllerCustomCommands iAudioPlayControllerCommands; + + // Tts custom commands + RTtsCustomCommands iTtsCustomCommands; + + // Pointer to controller event monitor + CMMFControllerEventMonitor* iControllerEventMonitor; + + // Reference to observer + MTtsClientUtilityObserver& iObserver; + + // Source and sink handle info + TMMFMessageDestination iSourceHandle; + TMMFMessageDestination iSinkHandle; + + // Duration of the current TTS "clip" + TTimeIntervalMicroSeconds iDuration; + + // Latest read position of synthesising + TTimeIntervalMicroSeconds iPosition; + + // Plugin priority settings. + TMMFPrioritySettings iPrioritySettings; + + // Duration of current TTS 'clip' + TTimeIntervalMicroSeconds iTime; + + // Registered styles, these will be kept in two places: locally + // in TtsUtility and in TtsHwDevice in server side. + RArray iStyles; + + // Registered style IDs. (internal to TtsUtility) + RArray iInternalStyleIDs; + + // Registered style IDs. (plugin id) + RArray iControllerStyleIDs; + + // Increased numbering for style ids + TTtsStyleID iCurrentStyleID; + + // Flag to tell if playback should be started immediately after priming + // has finished. + TBool iPlayImmediately; + + // Counter to tell how many times playback should be repeated. + TInt iRepeats; + + // Trailing silence when repeating the playback + TTimeIntervalMicroSeconds32 iTrailingSilence; + + // UID of controller plugin which has been created + TUid iOpenPlugin; + + // Etrue if user has opened plugin by calling function OpenPluginL() + TBool iPluginOpenedExplicitly; + + // Parsed text which is given to the controller plugin + CTtsParsedText* iParsedText; + + // Default style structure + TTtsStyle iDefaultStyle; + + // Uid of data sink to be used + TUid iUidOfDataSink; + + // Output file handle if data sink is set to file output + RFile iFile; + }; + +#endif // TTSUTILITY_H + +// End of File + + +