/*

* Copyright (c) 2004 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:  DevTTS interface for Text-to-Speech

*

*/

#ifndef DEVTTS_H

#define DEVTTS_H

//  INCLUDES

#include <e32base.h>

#include <e32def.h>

// TTSCommon include

#include <nssttscommon.h>

// CONSTANTS

const TInt KDevTTSBalanceRight = 100;

const TInt KDevTTSBalanceRightMiddle = 50;

const TInt KDevTTSBalanceMiddle = 0;

const TInt KDevTTSBalanceLeftMiddle = -50;

const TInt KDevTTSBalanceLeft = -100;

// DATA TYPES

enum TDevTTSEvent

    {

    EDevTTSEventComplete

    };

enum TDevTTSOutputMode

    {

    EDevTTSSoundDeviceMode = 0,

    EDevTTSClientMode

    };

enum TDevTTSAudioPreference

    {

    EDevTTSPriorityPreferenceNone = 0,

    EDevTTSPriorityPreferenceTime, 

    EDevTTSPriorityPreferenceQuality,

    EDevTTSPriorityPreferenceTimeAndQuality 

    };

// FORWARD DECLARATIONS

class CTTSAlgorithmManager;

// CLASS DECLARATIONS

/**

*  MDevTTSObserver

*

*  Interface for a set of DevTTS callback functions.

*

*  This mixin class is intended to be inherited by the DevTTS client. Functions

*  of this class get called when DevTTS specific events occur.

*

*  @lib nssdevtts.lib

*  @since 2.8

*/

class MDevTTSObserver

    {

    public:  // New functions

        /**

        * Invoked by DevTTS when it needs a configuration data package.

        *

        * @since 2.8

        * @param "TUint32 aPackageType" Packege type identifier

        * @param "TUint32 aPackageID" Package identifier

        * @param "TUint32 aStartPosition" Start position in bytes from beginning of data

        * @param "TUint32 aEndPosition" End index in bytes. If the position is bigger 

        *         than the size of data package, the end part will be returned.

        *

        * @return Pointer to created data buffer. NULL if failure. User must 

        *         take care of the buffer deletion after usage.

        */

        virtual HBufC8* MdtoConfigurationData( TUint32 aPackageType, 

                                               TUint32 aPackageID, 

                                               TUint32 aStartPosition, 

                                               TUint32 aEndPosition ) = 0;

        /**

        * Called by DevTTS when an event occured. EDevTTSEventComplete is the only

        * event that can happen currently.

        *

        * @since 2.8

        * @param "TDevTTSEvent aEvent"

        *         Event code

        * @param "TInt aStatus"

        *         Error code. KErrNone if success, one of the system level

        *         error codes otherwise.

        */

        virtual void MdtoEvent( TDevTTSEvent aEvent, TInt aStatus ) = 0;

        /**

        * Called by DevTTS device when output mode is EDevTTSClientMode and a 

        * new audio buffer has been filled by the synthesizer. 

        *

        * @since 2.8

        * @param "TDesC8& aBuffer"

        *         Synthesized audio buffer.

        */

        virtual void MdtoProcessBuffer( const TDesC8& aBuffer ) = 0;

    };

/**

*  CDevTTS is the interface towards DevTTS module. Actual implementation is

*  not included in this class.

*

*  @lib nssdevtts.lib

*  @since 2.8

*/

class CDevTTS : public CBase

    {

    public:  // Constructors and destructor

        /**

        * Two-phased constructor.

        */

        IMPORT_C static CDevTTS* NewL( MDevTTSObserver& aObserver/*, CConsoleBase* console*/ );

        /**

        * Destructor.

        */

        IMPORT_C ~CDevTTS();

    public: // New functions

        /**

        * Adds a new style to the collection. If equal style exists already,

        * new style is not added.

        * Will leave if an error occurs. Likely errors are: KErrNoMemory,

        * not enough memory to add new style. KErrNotSupported, the style 

        * is not supported. KErrArgument, the style contains an imposible 

        * value.

        *

        * @since 2.8

        * @param "TTtsStyle& aStyle"

        *        Reference to the style which will be added to the style 

        *        collection.

        *

        * @return Identifier of added style.

        */

        IMPORT_C TTtsStyleID AddStyleL( const TTtsStyle& aStyle );

        /**

        * Returns the current balance setting.

        *

        * @since 2.8

        * @return Balance value.

        */

        IMPORT_C TInt Balance();

        /**

        * Notifies that the buffer has been processed. The 

        * method is used if output mode of synthesizing is 

        * EDevTTSClientMode.

        *

        * @since 2.8

        * @param "TDesC8& aBuffer"

        *        The buffer which has been processed.

        */

        IMPORT_C void BufferProcessed( const TDesC8& aBuffer );

        /**

        * Request a pointer to the custom interface. Currently not in use.

        * 

        * @since 2.8

        * @param "TUid aInterfaceID"

        *        Custom interface identifier.

        *

        * @return Pointer to custom interface. NULL if interface is not 

        *         found or initiation failures.

        */

        IMPORT_C TAny* CustomInterface( TUid aInterfaceID );

        /**

        * Deletes style.

        * 

        * @since 2.8

        * @param "TTtsStyleID aStyleID" Identifier of style to be deleted.

        */

        IMPORT_C void DeleteStyleL( TTtsStyleID aStyleID );

        /**

        * Gives current position of synthesizing. The method will leave if an 

        * error occurs. Likely errors are: KErrNotReady, no synthesizing is 

        * ongoing.

        * 

        * @since 2.8

        * @param "TTimeIntervalMicroSeconds& aTime"

        *        Time of the synthesizing position

        */

        IMPORT_C void GetPositionL( TTimeIntervalMicroSeconds& aTime ) const;

        /**

        * Gives current position of synthesizing. The method will leave if an 

        * error occurs. Likely errors are: KErrNotReady, no synthesizing is 

        * ongoing.

        * 

        * @since 2.8

        * @param "TTtsSegment& aSegment"

        *        Current segment which is synthesized, out parameter

        * @param "TInt& aWordIndex"

        *        Index of the current word, starting from the begining of 

        *        current segment

        */

        IMPORT_C void GetPositionL( TTtsSegment& aSegment, TInt& aWordIndex ) const;

        /**

        * Tells if language is supported by the TTS engine or not.

        * 

        * @since 2.8

        * @param "TLanguage aLanguage"

        *        Language code

        *

        * @return ETrue if supported, EFalse otherwise

        */

        IMPORT_C TBool IsLanguageSupported( TLanguage aLanguage ) const;

        /**

        * Returns maximum volume value.

        * 

        * @since 2.8

        * @return Maximum volume.

        */

        IMPORT_C TInt MaxVolume();

        /**

        * Gives number of styles.

        * 

        * @since 2.8

        * @return Number of styles.

        */

        IMPORT_C TUint16 NumberOfStyles() const;

        /**

        * Pauses synthesis process.

        * @since 2.8

        */

        IMPORT_C void Pause();

        /**

        * Prepares for synthesis. The method will leave if an 

        * error occurs. Likely errors are: KErrInUse, synthesizing is 

        * currently ongoing. KErrNoMemory, not enough memory to start 

        * synthesis. KErrNotSupport, requested function is not supported.

        * 

        * @since 2.8

        * @param "MTtsSegmentStream& aStream"

        *        Stream to be synthesized.

        */

        IMPORT_C void PrimeSynthesisL( MTtsSegmentStream& aStream );

        /**

        * Prepares for synthesis. The method will leave if an 

        * error occurs. Likely errors are: KErrInUse, synthesizing is 

        * currently ongoing. KErrNoMemory, not enough memory to start 

        * synthesis. KErrNotSupport, requested function is not supported.

        * 

        * @since 2.8

        * @param "CTtsParsedText& aText"

        *        Text containing multiple segments to be synthesized.

        */

        IMPORT_C void PrimeSynthesisL( CTtsParsedText& aText );

        /**

        * Sets the priority for audio playback if in EDevTTSSoundDeviceMode.

        * 

        * @since 2.8

        * @param "TInt aPriority"

        *        Priority value.

        * @param "TDevTTSAudioPreference aPref"'

        *        Preference setting. Quality, time or both.

        */

        IMPORT_C void SetAudioPriority( TInt aPriority, TDevTTSAudioPreference aPref );

        /**

        * Sets the audio output routing

        * 

        * @since 3.2

        * @param "TInt aAudioOutput"

        *        New output.

        */

        IMPORT_C void SetAudioOutputL( TInt aAudioOutput );

        /**

        * Sets the playback device balance. Affects only when DevTTS is in 

        * EDevTTSSoundDeviceMode. Illegal values are neglected.

        * 

        * @since 2.8

        * @param "TInt aBalance" Balance to be set. 

        */

        IMPORT_C void SetBalance( TInt aBalance );

        /**

        * Sets new position for synthesizing. The method will leave if an 

        * error occurs. Likely errors are: KErrNotReady, no synthesizing is 

        * ongoing. KErrArgument, position cannot be set.

        * 

        * @since 2.8

        * @param "TTimeIntervalMicroSeconds& aTime"

        *        Time of the synthesizing postion.

        */

        IMPORT_C void SetPositionL( const TTimeIntervalMicroSeconds& aTime );

        /**

        * Sets new position for synthesizing. The method will leave if an 

        * error occurs. Likely errors are: KErrNotReady, no synthesizing is 

        * ongoing. KErrArgument, position cannot be set.

        * 

        * @since 2.8

        * @param "TTtsSegment& aSegment"

        *        The segment being synthesized.

        * @param "TInt aWordIndex"

        *        The index of word being synthesized.

        */

        IMPORT_C void SetPositionL( const TTtsSegment& aSegment, TInt aWordIndex );

        /**

        * Sets the playback device volume. Affects only when DevTTS is in 

        * EDevTTSSoundDeviceMode. Range is from 0..MaxVolume(). Illegal values 

        * are neglected.

        * 

        * @since 2.8

        * @param "TInt aVolume" Volume setting.

        */

        IMPORT_C void SetVolume( TInt aVolume );

        /**

        * Sets the volume ramp duration. Start and end volumes must be set with

        * SetVolume() function.

        * 

        * @since 2.8

        * @param "TTimeIntervalMicroSeconds& aRampDuration" 

        *        Ramp duration in microseconds.

        */

        IMPORT_C void SetVolumeRamp( const TTimeIntervalMicroSeconds& aRampDuration );

        /**

        * Stops synthesizing and releases resources of synthesizing. 

        * The method does nothing if already stopped.

        * @since 2.8

        */

        IMPORT_C void Stop();

        /**

        * Receives style information. The method will leave if an error 

        * occurs. Likely errors are: KErrNotFound, style identifier not 

        * found. 

        * 

        * @since 2.8

        * @param "TTtsStyle& aStyle"

        *        Reference to style object where to assign the requested style.

        * @param "TTtsStyleID aStyleID"

        *        Style identifier.

        */

        IMPORT_C TTtsStyle& StyleL( TTtsStyleID aStyleID ) const;

        /**

        * Receives style information. The method will leave if an error 

        * occurs. Likely errors are: KErrArgument, index is out of bounds.

        * 

        * @since 2.8

        * @param "TTtsStyle& aStyle"

        *        Reference to style object where to assign the requested style.

        * @param "TUint16 aIndex"

        *        Index to style: 0..NumberOfStyles().

        */

        IMPORT_C TTtsStyle& StyleL( TUint16 aIndex ) const;

        /**

        * Starts synthesizing the text. The method is asynchronous, as soon

        * as the request has been placed, function call will return. 

        * MDevTTSObserver::MdtoEvent will be called when synthesizing finishes.

        * The method will leave if an error occurs. Likely errors are: 

        * KErrNoMemory, not enough memory. 

        * KErrInUse, synthesizing is currently ongoing

        * 

        * @since 2.8

        * @param "TDevTTSOutputMode aOutputMode"

        *        Either use a sound device (EDevTTSSoundDeviceMode) or client 

        *        using callback (EDevTTSClientMode)

        */

        IMPORT_C void SynthesizeL( TDevTTSOutputMode aOutputMode );

        /**

        * Returns current playback volume.

        * 

        * @since 2.8

        * @return Volume setting.

        */       

        IMPORT_C TInt Volume();

        /** 

        * Calls language identification for a given text.

        *

        * @since 3.0M

        * @param "CTtsParsedText& aText" Text

        * @param "TInt aNumberOfGuesses" Maximum number of guesses that will be provided

        * @param "RArray<TLanguage>& aLanguages" Output parameter which will contain the languages

        * @param "RArray<TInt>& aScores" Scores

        */

        IMPORT_C void LanguageIdentificationL( CTtsParsedText& aText, 

                                               TInt aNumberOfGuesses, 

                                               RArray<TLanguage>& aLanguages,

                                               RArray<TInt>& aScores );

        /**

        * Calls Natural Language Processing (NLP) to normalize text.

        *

        * @since 3.0M

        * @param "CTtsParsedText& aText" Text which will be normalized

        */

        IMPORT_C void NormalizeTextL( CTtsParsedText& aText );

        /**

        * Calls Natural Language Processing (NLP) to normalize and segment text.

        *

        * @since 3.0M

        * @param "CTtsParsedText& aText" Text which will be normalized

        */

        IMPORT_C void NormalizeAndSegmentTextL( CTtsParsedText& aText );

    public: // Functions from base classes

    protected:  // New functions

    protected:  // Functions from base classes

    private:

        /**

        * C++ default constructor.

        */

        CDevTTS();

        /**

        * By default Symbian 2nd phase constructor is private.

        */

        void ConstructL( MDevTTSObserver& aObserver/*, CConsoleBase* console*/ );

        /**

        * Prohibit copy constructor

        */

        CDevTTS( const CDevTTS& );

        /** 

        * Prohibit assignment operator

        */

        CDevTTS& operator=( const CDevTTS& );

    public:     // Data

    protected:  // Data

    private:    // Data

        // Pointer to the implementation class

        CTTSAlgorithmManager* iImpl;

        // Reserved pointer for future extension

        TAny* iReserved;

    public:     // Friend classes

    protected:  // Friend classes

    private:    // Friend classes

    };

#endif // DEVTTS_H   

// End of File