diff -r cad71a31b7fc -r e36f3802f733 speechsrv_plat/speech_synthesis_clientserver_api/inc/speechsynthesis.h
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/speechsrv_plat/speech_synthesis_clientserver_api/inc/speechsynthesis.h	Wed Sep 01 12:29:17 2010 +0100
@@ -0,0 +1,428 @@
+/*
+* Copyright (c) 2006-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:  Client side header of Speech synthesis server
+*
+*/
+
+
+#ifndef SPEECHSYNTHESIS_H
+#define SPEECHSYNTHESIS_H
+
+// INCLUDES
+
+#include <e32std.h>
+
+
+// CONSTANTS
+
+/**
+* Maximum length of text-to-speech voice name. 
+* 
+* @see TVoiceName
+*/
+const TInt KMaxNameLength = 64;
+
+/**
+* Text-to-speech voice name type definition. 
+* 
+* @see TVoice
+*/
+typedef TBuf<KMaxNameLength> TVoiceName;
+
+
+// CLASSES
+
+/**
+* Class containing basic information of text-to-speech voice. 
+*/
+class TVoice
+    {
+
+    public:
+
+        /**
+        * Language spoken by the voice
+        */
+        TLanguage               iLanguage;
+
+        /**
+        * Name of the voice
+        */
+        TVoiceName              iVoiceName;
+    
+        /**
+        * Sampling rate of the voice
+        */
+        TInt                    iSamplingRate;
+
+        /**
+        * TVoice constructor
+        */
+        inline TVoice():
+            iLanguage( ELangNone ),
+            iSamplingRate( KErrNotFound )
+            {
+            // Nothing
+            }
+    };
+
+/**
+* Speech synthesis client side interface
+*
+
+* @code
+* // Simple example how to use synthesis server synchronously
+* _LIT( KText, "This is a text sample" );
+* RSpeechSynthesis s;
+* TRequestStatus status;
+*
+* // Open connection
+* s.Open();
+*
+* // Initialise
+* s.InitialiseSynthesis( KText, status );
+* User::WaitForRequest( status );
+*
+* // Start synthesis when initialisation is ready
+* s.Synthesise( status );
+* User::WaitForRequest( status );
+*
+* // Close connection
+* s.Close();
+* @endcode
+*
+* @code
+* // Another example how to use synthesis server synchronously
+* _LIT( KText, "Second text sample" );
+* RSpeechSynthesis s;
+* TRequestStatus status;
+*
+* // Open connection
+* s.Open();
+*
+* // Set volume to maximum value    
+* s.SetVolumeL( * s.MaxVolumeL() );
+*
+* // Set speaking rate to half of maximum value
+* s.SetSpeakingRateL( * s.MaxSpeakingRateL() / 2 );
+* 
+* // Set synthesis language but leave voice name open
+* TVoice voice;
+* voice.iLanguage = User::Language();
+* s.SetVoiceL( voice );
+*
+* // Initialise
+* s.InitialiseSynthesis( KText, status );
+* User::WaitForRequest( status );
+* 
+* // Ask estimated duration of synthesis. 
+* // Note: Leaves if current TVoice doesn't support duration
+* TTimeIntervalMicroSeconds duration = s.DurationL();
+*
+* // Start synthesis when initialisation is ready
+* s.Synthesise( status );
+* User::WaitForRequest( status );
+*
+* // Close connection
+* s.Close();
+* @endcode
+*/
+class RSpeechSynthesis : public RSessionBase
+    {
+    
+    public:
+        
+        /**
+        * Possible parameter values for SetAudioOutputL()
+        * 
+        * @see RSpeechSynthesis::SetAudioOutputL()
+        */
+        enum TTtsAudioOutput
+        	{
+        	ETtsOutputDefault = 0,  ///< Default
+        	ETtsOutputAll = 1,      ///< All output devices are used
+        	ETtsOutputNoOutput = 2, ///< No output
+        	ETtsOutputPrivate = 3,  ///< Private output device is used
+        	ETtsOutputPublic = 4    ///< Public output device is used
+        	};
+        
+    public:
+        
+        /**
+        * Constructor
+        */
+        IMPORT_C RSpeechSynthesis();
+        
+        /**
+        * Connect to synthesis server
+        *
+        * @return KErrNone if successful, otherwise system-wide error code. 
+        */
+        IMPORT_C TInt Open();
+        
+        /**
+        * Close connection to synthesis server
+        */    
+        IMPORT_C void Close();
+        
+        /**
+        * Initialise text to be synthesised. If there is synthesis already 
+        * ongoing aStatus will be completed with KErrInUse. 
+        * 
+        *
+        * @param aText Text to be synthesized. Text has to be valid until 
+        *        aStatus is completed because this function is asynchronous 
+        *        and the request that it represents may not complete until 
+        *        some time after the call to the function has returned. 
+        *        It is important, therefore, that this descriptor remain valid, 
+        *        or remain in scope, until you have been notified that 
+        *        the request is complete.
+        * @param aStatus Status of priming. 
+        */
+        IMPORT_C void InitialiseSynthesis( const TDesC& aText,
+                                           TRequestStatus& aStatus );
+        
+        /**
+        * Initialise text to be synthesised to the file. If there is synthesis 
+        * already ongoing aStatus will be completed with KErrInUse. 
+        *
+        * @param aText Text to be synthesized. Text has to be valid until 
+        *        aStatus is completed because this function is asynchronous 
+        *        and the request that it represents may not complete until 
+        *        some time after the call to the function has returned. 
+        *        It is important, therefore, that this descriptor remain valid, 
+        *        or remain in scope, until you have been notified that 
+        *        the request is complete.
+        * @param aFileName Output is written to this file. File name has to be
+        *        valid until aStatus is completed. Client should have capabilities 
+        *        needed for writing location defined in aFileName, otherwise aStatus
+        *        will be completed by KErrPermissionDenied. 
+        * @param aStatus Status of priming
+        */
+        IMPORT_C void InitialiseSynthesis( const TDesC& aText, 
+                                           const TFileName& aFileName,
+                                           TRequestStatus& aStatus ); 
+        
+        /** 
+        * @todo Not supported. aStatus will be always completed with KErrNotSupported.
+        *
+        * Initialise text to be synthesised to the descriptor. If there is synthesis 
+        * already ongoing aStatus will be completed with KErrInUse. 
+        *
+        * @param aText Text to be synthesized. Text has to be valid until 
+        *        aStatus is completed because this function is asynchronous 
+        *        and the request that it represents may not complete until 
+        *        some time after the call to the function has returned. 
+        *        It is important, therefore, that this descriptor remain valid, 
+        *        or remain in scope, until you have been notified that 
+        *        the request is complete.
+        * @param aDataBuffer Reference to a descriptor where output is stored
+        *        after Synthesise() is called. If all the data does not fit 
+        *        into aDataBuffer Synthesise can be called several times. 
+        * @param aStatus Status of priming
+        */
+        IMPORT_C void InitialiseSynthesis( const TDesC& aText,
+                                           TDes8& aDataBuffer, 
+                                           TRequestStatus& aStatus );
+        
+        /**
+        * Synthesise the text or resume paused synthesis. 
+        * InitialiseSynthesis() has to be called succesfully before call to 
+        * this function will succeed. aStatus is completed with KErrNotReady 
+        * if initialisation has not been done. 
+        *
+        * @param aStatus Status of synthesis
+        *
+        * @see RSpeechSynthesis::InitialiseSynthesis() 
+        * @see RSpeechSynthesis::PauseL() 
+        */
+        IMPORT_C void Synthesise( TRequestStatus& aStatus );     
+        
+        /**
+        * Stop ongoing synthesis. Ongoing synthesis request is completed 
+        * with KErrAbort. Does nothing if there is no synthesis ongoing. 
+        *
+        * @leave KErrInUse if request is made to stop other client's synthesis. 
+        */
+        IMPORT_C void StopL();
+        
+        /**
+        * Pause synthesis. Resuming can be done by calling Synthesize(). 
+        * Ongoing synthesis request is completed with KErrCancel. 
+        *
+        * @leave KErrNotSupported if trying to pause synthesis to file. 
+        * @leave KErrNotReady if there is no synthesis ongoing. 
+        */
+        IMPORT_C void PauseL();
+        
+        /**
+        * Returns estimated duration of synthesis. This function returns valid 
+        * duration only after synthesis is initialised and before synthesis has
+        * completed. 
+        *
+        * @return Estimated duration of speech synthesis playback. 
+        *
+        * @leave KErrNotReady if state is incorrect
+        * @leave KErrNotSupported if current voice settings doesn't support 
+        *        duration information
+        */
+        IMPORT_C TTimeIntervalMicroSeconds DurationL();
+        
+        /**
+        * Get supported synthesis languages
+        *
+        * @param aLanguages Contains supported languages after function call
+        *
+        */
+        IMPORT_C void GetLanguagesL( RArray<TLanguage>& aLanguages );
+        
+        /**
+        * Get available voices 
+        *
+        * @param aVoices Contains supported voices in TVoice structure after 
+        *        the function call. 
+        * @param aLanguage Defines a language that returned voices can speak. 
+        *
+        */
+        IMPORT_C void GetVoicesL( RArray<TVoice>& aVoices, TLanguage aLanguage );
+        
+        /**
+        * Get current voice. 
+        *
+        * @return Current voice. 
+        *
+        */
+        IMPORT_C TVoice VoiceL();
+        
+        /**
+        * Change voice. Change is effective after next InitialiseSynthesis() call 
+        * is made and until new SetVoiceL() call is made or Close() is called. 
+        *
+        * @param aVoice New voice to be set. aVoice.iLanguage is the only mandatory 
+        *        parameter,others can be undefined and server may ignore 
+        *        those if invalid values are given. 
+        *
+        * @leave KErrArgument if aVoice is not valid
+        */
+        IMPORT_C void SetVoiceL( const TVoice& aVoice ); 
+        
+        /**
+        * Returns maximum speaking rate.
+        *
+        * @return Maximum speaking rate
+        *
+        */
+        IMPORT_C TInt MaxSpeakingRateL(); 
+        
+        /**
+        * Returns the current speaking rate value.
+        *
+        * @return Current speaking rate
+        *
+        */
+        IMPORT_C TInt SpeakingRateL(); 
+        
+        /**
+        * Sets the speaking rate. Range is 1..MaxSpeakingRateL(). Setting will 
+        * be effective after next InitialiseSynthesis() call and until new rate 
+        * is set or Close() is called. Note: All voices doesn't support speaking 
+        * rate changes and in that case there is no audible change. 
+        *
+        * @param aSpeakingRate Rate value
+        *
+        * @leave KErrArgument if speaking rate is out of range. 
+        *
+        * @see MaxSpeakingRateL()
+        */
+        IMPORT_C void SetSpeakingRateL( TInt aSpeakingRate ); 
+        
+        /**
+        * Get maximum volume
+        *
+        * @return Maximum volume
+        *
+        */
+        IMPORT_C TInt MaxVolumeL(); 
+        
+        /**
+        * Get current volume.
+        *
+        * @return Volume level between 0 and MaxVolumeL()
+        *
+        */
+        IMPORT_C TInt VolumeL(); 
+        
+        /**
+        * Change volume. Will be effective until new volume is set or Close()
+        * is called.
+        *
+        * @param aVolume New volume, accepted values are in range from 0 to MaxVolumeL()
+        *
+        * @leave KErrArgument if volume value is out of range, 
+        *
+        * @see MaxVolumeL()
+        */
+        IMPORT_C void SetVolumeL( TInt aVolume ); 
+        
+        /**
+        * Sets the playback priority and preference values. Setting will 
+        * be effective after next InitialiseSynthesis() call and until new priority 
+        * is set or Close() is called. Client needs Nokia VID to use
+        * this function. 
+        *
+        * @param aPriority Audio priority
+        * @param aPreference Audio preference
+        *
+        * @leave KErrPermissionDenied if client doesn't have Nokia VID. 
+        */
+        IMPORT_C void SetAudioPriorityL( TInt aPriority, TInt aPreference ); 
+        
+        /**
+      	* Sets the audio output. Setting will be effective immediately and until
+      	* new value is set or connection closed. Client needs WriteDeviceData 
+      	* capability if setting output to ETtsOutputAll
+        *
+      	* @param aAudioOutput - where the audio is routed. 
+      	*
+      	* @leave KErrPermissionDenied if client doesn't have WriteDeviceData when
+      	*        setting output to ETtsOutputAll. 
+        *
+      	*/
+        IMPORT_C void SetAudioOutputL( TTtsAudioOutput aAudioOutput );
+        
+        /**
+        * Send custom command to the server. By using this function it is possible 
+        * to make adjustments to the synthesis process. 
+        * Note: Currently there is no supported commands. 
+        *
+        * @param aCommand A custom command 
+        * @param aValue Parameter value for aCommand 
+        * 
+        * @leave KErrNotSupported aCommand is not supported. 
+        * @leave KErrArgument if aValue is not valid. 
+        */
+        IMPORT_C void CustomCommandL( TInt aCommand, TInt aValue ); 
+        
+    private:
+        
+        /**
+        * Internal function used for handling initialisation. 
+        */
+        void DoInitialiseSynthesisL( const TDesC& aText, 
+                                     const TFileName& aFileName, 
+                                     TRequestStatus& aStatus ); 
+        
+    };
+    
+#endif // SPEECHSYNTHESIS_H