--- a/speechsrv_plat/speech_synthesis_clientserver_api/inc/speechsynthesis.h Thu Aug 19 09:56:14 2010 +0300
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,428 +0,0 @@
-/*
-* 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