/*

* 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:  This is the definition of the speech recognition utility.

*

*/

#ifndef NSSSISPEECHRECOGNITIONUTILITY_H

#define NSSSISPEECHRECOGNITIONUTILITY_H

// INCLUDES

#include <e32base.h>

#include <mmfcontroller.h>

#include <nsssispeechrecognitioncustomcommands.h>

#include <nsssispeechrecognitionutilityobserver.h>

#include <nsssispeechrecognitiondataclient.h>

#include <nsssispeechrecognitiondatacommon.h>

#include <nsssiutilitybase.h>

// FORWARD DECLARATIONS

class CSDClientResultSet;

// CLASS DECLARATION

/**

*  This is the main class of Speech Recognition Utility 

*

*  @lib nsssispeechrecognitionutility.lib

*  @since 2.0

*/

class CSISpeechRecognitionUtility : public CBase,

                                    public MSISpeechRecognitionUtilityBase, 

                                    public MMMFControllerEventMonitorObserver

{

public:

        /*

        * Creates instance of CSISpeechRecognitionUtility

        * Needed when dynamically loading nsssispeechrecognitionutility.dll

        * Direct users of CSISpeechRecognitionUtility should not use this.

        * Returns M-class pointer to MSISpeechRecognitionUtilityBase as TAny*

        *

        * @return Created instance

        */        

        IMPORT_C static TAny* CreateInstanceL();

        /**

        * Second phase of construction after CreateInstanceL call.

        * Needed when dynamically loading nsssispeechrecognitionutility.dll

        * Direct users of CSISpeechRecognitionUtility should not use this.

        *

        * @since 3.1

        * @param aClientUid Client UID for data ownership, other clients won't

        *                   be able to modify the data registered to certain client

        * @param aPluginUid UID of the plugin which will be used, KNullUid to 

        *                    search for suitable plugin

        * @param aObserver Callback observer reference

        */

        IMPORT_C void CreateInstanceSecondPhaseL( TUid aClientUid, 

                                                  TUid aPluginUid, 

                                                  MSISpeechRecognitionUtilityObserver& aObserver );

        /**

        * Factory function for creating this class.

        *

        * @since 2.0

        * @param    aSpeechRecognitionUtilityObserver    reference to event 

        *                                                observer class

        * @param    aClientUid                           client UID for data 

        *                                                ownership

        * @return   pointer to CSISpeechRecognitionUtility object

        */

        IMPORT_C static CSISpeechRecognitionUtility* NewL( 

                            MSISpeechRecognitionUtilityObserver& 

                            aSpeechRecognitionUtilityObserver, TUid aClientUid );

        /**

        * Factory function for creating this class.

        * Searches for a plugin, which supports the given

        * recognition mode. If no such plugin is found, leaves.

        *

        * @since 2.8

        * @param     aSpeechRecognitionUtilityObserver    reference to the event observer class

        * @param    aClientUid                            client UID for data ownership

        * @param    aPreferredMode                      Recognition technology (speaker

        *                                               independent or dependent)

        * @return    pointer to CSISpeechRecognitionUtility object

        */

        IMPORT_C static CSISpeechRecognitionUtility* NewL( 

                            MSISpeechRecognitionUtilityObserver& aSpeechRecognitionUtilityObserver,

                            TUid aClientUid,

                            TNSSRecognitionMode aPreferredMode );

        /**

        * Factory function for creating this class.

        * Loads the plugin with the given ID.

        *

        * @since 2.8

        * @param     aSpeechRecognitionUtilityObserver    reference to the event observer class

        * @param     aClientUid                           client UID for data ownership

        * @param     aMmfPluginUid                        UID of the speech recognition plugin

        * @return    pointer to CSISpeechRecognitionUtility object

        */

        IMPORT_C static CSISpeechRecognitionUtility* NewL( 

                            MSISpeechRecognitionUtilityObserver& aSpeechRecognitionUtilityObserver,

                            TUid aClientUid,

                            TUid aMmfPluginUid );

        /**

        * Factory function for creating this class. Leaves a pointer 

        * on the cleanup 

        *

        * @since 2.0

        * @param    aSpeechRecognitionUtilityObserver     reference to event

        *                                                 observer class

        * @param    aClientUid                            client UID for data 

        *                                                 ownership

        * @return    pointer to CSISpeechRecognitionUtility object

        */

        IMPORT_C static CSISpeechRecognitionUtility* NewLC( 

                            MSISpeechRecognitionUtilityObserver& 

                            aSpeechRecognitionUtilityObserver, TUid aClientUid );

        /**

        * Destructor

        *

        * @since 2.0

        */

        IMPORT_C ~CSISpeechRecognitionUtility();

        /**

        * Returns the engine properties specified by the engine property 

        * ID array. On return aPropertyValue contains an array of engine 

        * properties.

        *

        * @since 2.0

        * @param    aPropertyId      constant reference to array of engine 

        *                            property Ids

        * @param    aPropertyValue   reference to array of engine property 

        *                            values

        * @return   system wide error code

        */

        IMPORT_C TInt GetEngineProperties( const RArray<TInt>& aPropertyId, 

                        RArray<TInt>& aPropertyValue );

        /**

        * Adapts the speaker independent models to a specific speaker's voice.

        *

        * @since  2.8

        * @param  aResultSet     Recognition result N-Best

        * @param  aCorrect       Index to N-Best pointing the correct result.

        * @return system wide error code

        */

        IMPORT_C TInt Adapt( const CSIClientResultSet& aResultSet,

                             TInt aCorrect );

        /**

        * Adds a new pronunciation for the given text phrase into the 

        * specified lexicon.

        *

        * @since    2.8

        * @param    aLexiconID          lexicon Id, where the new 

        *                               pronunciation is added to

        *           aTextForTraining    Text to be trained

        *           aLanguage           Pronunciation language

        *           aPronunciationID    reference where a new pronunciation 

        *                               Id is assigned to

        * @return   system wide error code

        */

        IMPORT_C TInt AddPronunciation( TSILexiconID aLexiconID,

                        const TDesC& aTextForTraining,

                        TLanguage aLanguage,

                        TSIPronunciationID& aPronunciationID);

        /**

        * Adds a new rule for the given pronunciation into the 

        * specified grammar.

        *

        * @since    2.0

        * @param    aGrammarID            grammar Id, where the new rule is 

        *                                added to

        * @param    aLexiconID            lexicon Id

        * @param    aPronunciationID    pronunciation Id

        * @param    aRuleID                reference where a new rule Id is 

        *                                assigned to

        * @return    system wide error code

        */

        IMPORT_C TInt AddRule( TSIGrammarID aGrammarID,

                        TSILexiconID aLexiconID,

                        TSIPronunciationID aPronunciationID,

                        TSIRuleID& aRuleID );

        /**

        * Adds a new rule variant for the given pronunciation into the 

        * specified grammar.

        *

        * @since    2.8

        * @param    aGrammarID            grammar Id, where the new rule is 

        *                                added to

        * @param    aRuleID                the rule Id, which will contain this variant

        * @param    aPronunciationIDs    the phrase is the concatenation

        *                               of these pronunciation IDs

        * @param    aRuleVariantID        reference where a new rule variant

        *                               Id is assigned to

        * @return    system wide error code

        */

        IMPORT_C TInt AddRuleVariant( TSIGrammarID aGrammarID,

                        TSILexiconID aLexiconID,

                        RArray<TSIPronunciationID>& aPronunciationIDs,

                        TSIRuleID aRuleID,

                        TSIRuleVariantID& aRuleVariantID );

        /**

        * Adds a new rule for the given phrase into the 

        * specified grammar.

        *

        * @since    2.8

        * @param    aTextArray            the text to be trained, divided in to words.

        *                               The phrase is the concatenation of these words.

        * @param    aLanguageArray      pronunciations will be generated for these languages

        * @param    aLexiconID          lexicon, where to add pronunciations

        * @param    aGrammarID          grammar, where to add rules

        * @param    aRuleID             the ID of the rule will be placed on this variable.

        * @return    system wide error code

        */

        IMPORT_C TInt AddVoiceTag( MDesCArray& aTextArray,

                                   const RArray<TLanguage>& aLanguageArray,

                                   TSILexiconID aLexiconID,

                                   TSIGrammarID aGrammarID,

                                   TSIRuleID& aRuleID );

        /**

        * Adds a new rules for the given phrases into the 

        * specified grammar.

        *

        * @since    2.8

        * @param    aTextArrayArray     Array of text arrays. The phrase k is the concatenation

        *                               of texts in array k.

        * @param    aLanguageArray      pronunciations will be generated for these languages

        * @param    aLexiconID          lexicon, where to add pronunciations

        * @param    aGrammarID          grammar, where to add rules

        * @param    aRuleID             the ID of the rule will be placed on this variable.

        *                               If some of the names fail while others succeed,

        *                               KInvalidRuleID will be placed to the array.

        * @return    system wide error code

        */

        IMPORT_C TInt AddVoiceTags( const RPointerArray<MDesCArray> &aTextArrayArray,

                                    const RArray<TLanguage> &aLanguageArray,

                                    TSILexiconID aLexiconID,

                                    TSIGrammarID aGrammarID, 

                                    RArray<TSIRuleID>& aRuleIDArray );

        /**

        * Adds a new rule for the given phrase into the 

        * specified grammar.

        *

        * @since 3.1

        * @param aTextArray        The text to be trained, divided in to words.

        *                          The phrase is the concatenation of these words.

        * @param aLanguageArray    Pronunciations will be generated for these languages

        * @param aLexiconID        Lexicon, where to add pronunciations

        * @param aGrammarID        Grammar, where to add rules

        * @param aRuleID           The ID of the rule will be placed on this variable.

        *

        * @return System wide error code

        */

        IMPORT_C TInt AddVoiceTag( MDesCArray& aTextArray,

                                   const RArray<RLanguageArray>& aLanguageArray,

                                   TSILexiconID aLexiconID,

                                   TSIGrammarID aGrammarID,

                                   TSIRuleID& aRuleID );

        /**

        * Adds a new rules for the given phrases into the 

        * specified grammar.

        *

        * @since 3.1

        * @param aTextArrayArray     Array of text arrays. The phrase k is the concatenation

        *                            of texts in array k.

        * @param aLanguageArray      pronunciations will be generated for these languages

        * @param aLexiconID          lexicon, where to add pronunciations

        * @param aGrammarID          grammar, where to add rules

        * @param aRuleID             the ID of the rule will be placed on this variable.

        *                            If some of the names fail while others succeed,

        *                            KInvalidRuleID will be placed to the array.

        * @return System wide error code

        */

        IMPORT_C TInt AddVoiceTags( const RPointerArray<MDesCArray>& aTextArrayArray,

                                    const RArray<RLanguageArray>& aLanguageArray,

                                    TSILexiconID aLexiconID,

                                    TSIGrammarID aGrammarID, 

                                    RArray<TSIRuleID>& aRuleIDArray );

        /**

        * Cancels the current operation

        *    

        * @since 2.0

        */

        IMPORT_C void Cancel();

        /**

        * Saves the changes into a permanent storage.

        *

        * @since 2.0

        * @return    System-wide errors

        */

        IMPORT_C TInt CommitChanges();

        /**

        * Creates a new grammar.

        *    

        * @since 2.0

        * @param     aGrammarID            reference where grammar ID is stored

        * @return    system wide error codes

        */

        IMPORT_C TInt CreateGrammar( TSIGrammarID& aGrammarID );

        /**

        * Creates a new lexicon.

        *    

        * @since 2.0

        * @param     aLexiconID            reference where lexicon ID is stored

        * @return    system wide error codes

        */

        IMPORT_C TInt CreateLexicon( TSILexiconID& aLexiconID );

        /**

        * Creates a new rule.

        *    

        * @since 2.8

        * @param    aGrammarID          grammar, where the new rule is to be added

        * @param     aRuleID                reference where rule ID is stored

        * @return    system wide error codes

        */

        IMPORT_C TInt CreateRule( TSIGrammarID aGrammarID, TSIRuleID& aRuleID );

        /**

        * Loads the specified model bank into the recognizer;

        * done prior to recognition.

        *

        * @since 2.0

        * @param     ModelBankID            model bank Id

        * @return    system wide error codes

        */

        IMPORT_C TInt LoadModels( TSIModelBankID aModelBankID );

        /**

        * Loads the specified grammar into the recognizer;

        * done prior to recognition.

        *

        * @since 2.0

        * @param     aGrammarID            grammar ID

        * @return    system wide error codes

        */

        IMPORT_C TInt LoadGrammar( TSIGrammarID aGrammarID );

        /**

        * Reactivates a previously deactivated grammar.

        *

        * @since 2.0

        * @param     aGrammarID            grammar ID

        * @return    system wide error codes

        */

        IMPORT_C TInt ActivateGrammar( TSIGrammarID aGrammarID );

        /**

        * Deactivates a loaded grammar, so that it is not recognized.

        *

        * @since 2.0

        * @param     aGrammarID            grammar ID

        * @return    system wide error codes

        */

        IMPORT_C TInt DeactivateGrammar( TSIGrammarID aGrammarID );

        /**

        * Loads the specified lexicon into the recognizer; 

        * done prior to recognition.

        *

        * @since 2.0

        * @param     aLexiconID            lexicon ID

        * @return    system wide error codes

        */

        IMPORT_C TInt LoadLexicon( TSILexiconID aLexiconID );

        /**

        * Returns the number of models in the specified model bank.

        * @since    2.0

        * @param    aModelBankID        model bank Id

        * @param    aCount                reference where the number of 

        *                                models is set

        * @return    system wide error codes

        */

        IMPORT_C TInt GetModelCount( TSIModelBankID aModelBankID, 

                            TInt& aModelCount );

        /**

        * Ends the current recognition session. Resources allocated 

        * for recognition are freed.

        *

        * @since    2.0

        * @param    aModelBankID        reference where a new model bank Id is 

        *                                assigned to

        * @return    system wide error codes

        */

        IMPORT_C TInt EndRecSession();

        /**

        * Starts a new recognition session.

        *

        * @since    2.0

        * @param    aMode                recognition mode

        * @return    system wide error codes

        */

        IMPORT_C TInt StartRecSession( TNSSRecognitionMode aMode );

        /**

        * Initiates speaker independent recognition; performed

        * following loading of model bank, lexicon, and grammar.

        *

        * @since    2.8

        * @param    aResultSet            reference where the recognition

        *                                result is set

        * @return    system wide error codes

        */

        IMPORT_C TInt Recognize( CSIClientResultSet& aResultSet );

        /**

        * Records uder utterance for training and recognition.

        *

        * @since    2.0

        * @param    aRecordTime            recording time in microseconds

        * @return    system wide error codes

        */

        IMPORT_C TInt Record( TTimeIntervalMicroSeconds32 aRecordTime );

        /**

        * Stops the recording. The difference with Cancel is that if

        * enough samples were recorded, a recognition result will be produced.

        *

        * @since    2.8

        * @param    aRecordTime            recording time in microseconds

        * @return    system wide error codes

        */

        IMPORT_C TInt EndRecord();

        /**

        * Pre-starts samping before Record call.

        * 

        * @since 3.2

        * @return System wide error code

        */

        IMPORT_C TInt PreStartSampling();

        /**

        * Removes the specified grammar from the permanent storage.

        * Removing a grammar will remove all rules within the grammar.

        *

        * @since    2.0

        * @param    aGrammarID            grammar Id

        * @return    system wide error codes

        */

        IMPORT_C TInt RemoveGrammar( TSIGrammarID aGrammarID );

        /**

        * Removes the specified pronunciation from the 

        * specified lexicon permanently.

        *

        * @since    2.0

        * @param    aLexiconID            lexicon Id

        * @param    aPronunciationID    pronunciation Id

        * @return    system wide error codes

        */

        IMPORT_C TInt RemovePronunciation( TSILexiconID aLexiconID, 

                        TSIPronunciationID aPronunciationID );

        /**

        * Removes the specified lexicon from the permanent storage.

        * Removing a lexicon will remove all pronunciations within the 

        * lexicon.

        *

        * @since    2.0

        * @param    aLexiconID            lexicon Id

        * @return    system wide error codes

        */

        IMPORT_C TInt RemoveLexicon( TSILexiconID aLexiconID );

        /**

        * Removes the specified model from the specified model bank 

        * permanently.

        *

        * @since    2.0

        * @param    aModelBankID        model bank Id

        * @param    aModelID            model Id

        * @return    system wide error codes

        */

        IMPORT_C TInt RemoveModel( TSIModelBankID aModelBankID, 

                        TSIModelID aModelID );

        /**

        * Removes the specified rule from the specified grammar permanently.

        *

        * @since    2.0

        * @param    aGrammarID            grammar Id

        * @param    aRuleID                rule Id

        * @return    system wide error codes

        */

        IMPORT_C TInt RemoveRule( TSIGrammarID aGrammarID, TSIRuleID aRuleID );

        /**

        * Removes multiple rules from the specified grammar permanently.

        *

        * @since    2.0

        * @param    aGrammarID            grammar Id

        * @param    aRuleID                rule Id