// Copyright (c) 2002-2009 Nokia Corporation and/or its subsidiary(-ies).
// All rights reserved.
// This component and the accompanying materials are made available
// under the terms of the License "Symbian Foundation License v1.0" to Symbian Foundation members and "Symbian Foundation End User License Agreement v1.0" to non-members
// which accompanies this distribution, and is available
// at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".
//
// Initial Contributors:
// Nokia Corporation - initial contribution.
//
// Contributors:
//
// Description:
//

#ifndef __SPEECHRECOGNITIONUTILITY_H__
#define __SPEECHRECOGNITIONUTILITY_H__

// INCLUDES

#include <e32base.h>
#include <mmf/common/mmfcontroller.h>
#include <mmf/common/speechrecognitioncustomcommands.h>
#include <mmf/common/speechrecognitiondataclient.h>
#include <speechrecognitionutilityobserver.h>


// CLASS DECLARATION

/**
@publishedAll
@released

This is the main class of Speech Recognition Utility.

@since  8.0
*/
class CSpeechRecognitionUtility : public CBase
	{
	class CBody;
public:

	/**
	Factory function for creating this class.

	@param	aClientUid
	        The UID of the client.
	@param 	aSpeechRecognitionUtilityObserver
	        A reference to the event observer class.

	@return	A pointer to CSpeechRecognitionUtility object

	@since  8.0
	*/
	IMPORT_C static CSpeechRecognitionUtility* NewL(
							MSpeechRecognitionUtilityObserver&
							aSpeechRecognitionUtilityObserver, TUid aClientUid );

	/**
	Factory function for creating this class. Leaves a pointer on the cleanup stack.

	@param  aSpeechRecognitionUtilityObserver		
	        A reference to the event observer class.
	@param  aClientUid
	        A client UID for data ownership.

	@return A pointer to a CSpeechRecognitionUtility object.

	@since  8.0
	*/
	IMPORT_C static CSpeechRecognitionUtility* NewLC(
							MSpeechRecognitionUtilityObserver&
							aSpeechRecognitionUtilityObserver, TUid aClientUid );

	/**
	Destructor.

	@since  8.0
	*/
	IMPORT_C ~CSpeechRecognitionUtility();

	/**
	Returns the engine properties specified by the engine property
	ID array. On return aPropertyValue contains an array of engine
	properties.

	@param  aPropertyId		
	        A constant reference to an array of engine property ID's.
	@param  aPropertyValue
	        A reference to an array of engine property values.

	@return An error code indicating if the function call was successful. KErrNone on success, otherwise
	        another of the system-wide error codes.

	@since  8.0
	*/
	IMPORT_C TInt GetEngineProperties( const RArray<TInt>& aPropertyId,
		RArray<TInt>& aPropertyValue );

	/**
	Adds a new pronunciation for the given model into the
	specified lexicon.
	
	@param  aLexiconID			
	        The lexicon ID, where the new pronunciation is added to.
	@param  aModelBankID		
	        The model bank ID.
	@param	aModelID			
	        The model ID.
	@param  aPronunciationID	
	        A reference where the new pronunciation ID is assigned to.

	@return An error code indicating if the function call was successful. KErrNone on success, otherwise
	        another of the system-wide error codes.

	@since  8.0
	*/
	IMPORT_C TInt AddPronunciation( TLexiconID aLexiconID,
		TModelBankID aModelBankID, TModelID aModelID,
		TPronunciationID& aPronunciationID );

	/**
	Adds a new rule for the given pronunciation into the
	specified grammar.

	@param  aGrammarID			
	        The grammar ID, where the new rule is added to.
	@param  aLexiconID			
	        The lexicon ID.
	@param  aPronunciationID	
	        The pronunciation ID.
	@param  aRuleID				
	        A reference where the new rule ID is assigned to.

	@return An error code indicating if the function call was successful. KErrNone on success, otherwise
	        another of the system-wide error codes.

	@since  8.0
	*/
	IMPORT_C TInt AddRule( TGrammarID aGrammarID, TLexiconID aLexiconID,
		TPronunciationID aPronunciationID, TRuleID& aRuleID );

	/**
	Cancels the current operation.

	@since 8.0
	*/
	IMPORT_C void Cancel();

	/**
	Commit the current train operation to the database.

	@return An error code indicating if the function call was successful. KErrNone on success, otherwise
	        another of the system-wide error codes.

	@since  8.0
	*/
	IMPORT_C TInt CommitChanges();

	/**
	Creates a new grammar.

	@param  aGrammarID			
	        A reference where grammar ID is stored.

	@return An error code indicating if the function call was successful. KErrNone on success, otherwise
	        another of the system-wide error codes.

	@since  8.0
	*/
	IMPORT_C TInt CreateGrammar( TGrammarID& aGrammarID );

	/**
	Creates a new lexicon.

	@param  aLexiconID			
	        A reference where lexicon ID is stored.

	@return An error code indicating if the function call was successful. KErrNone on success, otherwise
	        another of the system-wide error codes.

	@since  8.0
	*/
	IMPORT_C TInt CreateLexicon( TLexiconID& aLexiconID );

	/**
	Loads the specified model bank into the recognizer;
	done prior to recognition.

	@param  aModelBankID
			The Model bank ID

	@return An error code indicating if the function call was successful. KErrNone on success, otherwise
	        another of the system-wide error codes.

	@since  8.0
	*/
	IMPORT_C TInt LoadModels( TModelBankID aModelBankID );

	/**
	Loads the specified grammar into the recognizer;
	done prior to recognition.
	
	@param  aGrammarID			
	        The grammar ID.

	@return An error code indicating if the function call was successful. KErrNone on success, otherwise
	        another of the system-wide error codes.

	@since  8.0
	*/
	IMPORT_C TInt LoadGrammar( TGrammarID aGrammarID );

	/**
	Loads the specified lexicon into the recognizer;
	done prior to recognition.

	@param  aLexiconID			
	        The lexicon ID.

	@return An error code indicating if the function call was successful. KErrNone on success, otherwise
	        another of the system-wide error codes.

	@since  8.0
	*/
	IMPORT_C TInt LoadLexicon( TLexiconID aLexiconID );

	/**
	Returns the duration of the utterance for the specified model.

	@param  aModelBankID		
	        The model bank ID.
	@param  aModelID			
	        The model ID.
	@param  aDuration			
	        The reference where the duration of utterance is set.

	@return An error code indicating if the function call was successful. KErrNone on success, otherwise
	        another of the system-wide error codes.

	@since  8.0
	*/
	IMPORT_C TInt GetUtteranceDuration( TModelBankID aModelBankID,
		TModelID aModelID,
		TTimeIntervalMicroSeconds32& aDuration);

	/**
	Plays the previously trained utterance.

	@param  aModelBankID
	        The model bank ID.
	@param  aModelID
	        The model ID, whose utterance is played.

	@return An error code indicating if the function call was successful. KErrNone on success, otherwise
	        another of the system-wide error codes.

	@since  8.0
	*/
	IMPORT_C TInt PlayUtterance( TModelBankID aModelBankID,
		TModelID aModelID);

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

	@param  aModelBankID		
	        The model bank ID.
	@param  aModelCount			
	        The reference where the number of models is set.

	@return An error code indicating if the function call was successful. KErrNone on success, otherwise
	        another of the system-wide error codes.

	@since  8.0
	*/
	IMPORT_C TInt GetModelCount( TModelBankID aModelBankID, TInt& aModelCount );

	/**
	Ends the current recognition session. Resources allocated
	for recognition are freed.

	@return An error code indicating if the function call was successful. KErrNone on success, otherwise
	        another of the system-wide error codes.

	@since  8.0
	*/
	IMPORT_C TInt EndRecSession();

	/**
	Starts a new recognition session.

	@param  aMode				
	        The recognition mode.

	@return An error code indicating if the function call was successful. KErrNone on success, otherwise
	        another of the system-wide error codes.

	@since  8.0
	*/
	IMPORT_C TInt StartRecSession( TRecognitionMode aMode );

	/**
	Initiates recognition; performed following loading of
	model bank, lexicon, and grammar.

	@param  aResultSet			
	        A reference where the recognition result is set.

	@return An error code indicating if the function call was successful. KErrNone on success, otherwise
	        another of the system-wide error codes.

	@since  8.0
	*/
	IMPORT_C TInt Recognize( CSDClientResultSet& aResultSet );

	/**
	Records user utterance for training and recognition.

	@param  aRecordTime			
	        The recording time in microseconds.

	@return An error code indicating if the function call was successful. KErrNone on success, otherwise
	        another of the system-wide error codes.

	@since  8.0
	*/
	IMPORT_C TInt Record( TTimeIntervalMicroSeconds32 aRecordTime );

	/**
	Removes the specified grammar from the permanent storage. 

	Removing a grammar will remove all rules within the grammar.

	@param  aGrammarID			
	        The grammar ID.

	@return An error code indicating if the function call was successful. KErrNone on success, otherwise
	        another of the system-wide error codes.

	@since  8.0
	*/
	IMPORT_C TInt RemoveGrammar( TGrammarID aGrammarID );

	/**
	Removes the specified pronunciation from the specified lexicon permanently.

	@param  aLexiconID			
	        The lexicon ID.
	@param  aPronunciationID	
	        The pronunciation ID.

	@return An error code indicating if the function call was successful. KErrNone on success, otherwise
	        another of the system-wide error codes.

	@since  8.0
	*/
	IMPORT_C TInt RemovePronunciation( TLexiconID aLexiconID,
		TPronunciationID aPronunciationID );

	/**
	Removes the specified lexicon from the permanent storage.
	
	Removing a lexicon will remove all pronunciations within the lexicon.

	@param  aLexiconID			
	        The lexicon ID.

	@return An error code indicating if the function call was successful. KErrNone on success, otherwise
	        another of the system-wide error codes.

	@since  8.0
	*/
	IMPORT_C TInt RemoveLexicon( TLexiconID aLexiconID );

	/**
	Removes the specified model from the specified model bank
	permanently.

	@param  aModelBankID		
	        The model bank ID.
	@param  aModelID			
	        The model ID.

	@return An error code indicating if the function call was successful. KErrNone on success, otherwise
	        another of the system-wide error codes.

	@since  8.0
	*/
	IMPORT_C TInt RemoveModel( TModelBankID aModelBankID,
		TModelID aModelID );

	/**
	Removes the specified rule from the specified grammar permanently.

	@param  aGrammarID			
	        The grammar ID.
	@param  aRuleID
	        The rule ID.

	@return An error code indicating if the function call was successful. KErrNone on success, otherwise
	        another of the system-wide error codes.

	@since  8.0
	*/
	IMPORT_C TInt RemoveRule( TGrammarID aGrammarID, TRuleID aRuleID );

	/**
	Trains a new model into the specified model bank.

	@param  aModelBankID		
	        The model bank ID.
	@param  aModelID			
	        A reference where a new model ID is assigned to.

	@return An error code indicating if the function call was successful. KErrNone on success, otherwise
	        another of the system-wide error codes.

	@since  8.0
	*/
	IMPORT_C TInt Train( TModelBankID aModelBankID, TModelID& aModelID );

	/**
	Unloads the specified rule from the specified grammar in temporary memory, previously loaded 
	with LoadGrammarL.

	The rule in the permanent storage remains intact.

	@param  aGrammarID			
	        The grammar ID.
	@param  aRuleID				
	        The rule ID.

	@return An error code indicating if the function call was successful. KErrNone on success, otherwise
	        another of the system-wide error codes.

	@since  8.0
	*/
	IMPORT_C TInt UnloadRule( TGrammarID aGrammarID, TRuleID aRuleID );

	/**
	Sets the event handler for asynchronous events.

	@param  aSpeechRecognitionUtilityObserver		
	        A pointer to an observer.

	@since  8.0
	*/
	IMPORT_C void SetEventHandler( MSpeechRecognitionUtilityObserver*
		aSpeechRecognitionUtilityObserver );

	/**
	Returns all pronunciation IDs that exist in the specified lexicon.

	@param  aLexiconID
	        The lexicon ID.
	@param  aPronunciationIDs
	        A reference where pronunciation IDs are stored.

	@return An error code indicating if the function call was successful. KErrNone on success, otherwise
	        another of the system-wide error codes.

	@since  8.0
	*/
	IMPORT_C TInt GetAllPronunciationIDs( TLexiconID aLexiconID,
		RArray <TPronunciationID>& aPronunciationIDs );

	/**
	Returns all grammar IDs owned by the client.

	@param  aGrammarIDs			
	        A reference where rule IDs are stored.

	@return An error code indicating if the function call was successful. KErrNone on success, otherwise
	        another of the system-wide error codes.

	@since  8.0
	*/
	IMPORT_C TInt GetAllClientGrammarIDs(RArray <TGrammarID>& aGrammarIDs );

	/**
	Returns all lexicons owned by the client.

	@param  aLexiconIDs	
	        A reference where lexicon IDs are stored.

	@return An error code indicating if the function call was successful. KErrNone on success, otherwise
	        another of the system-wide error codes.

	@since  8.0
	*/
	IMPORT_C TInt GetAllClientLexiconIDs(RArray <TLexiconID>& aLexiconIDs );

	/**
	Returns all modelbank IDs owned by the client.

	@param  aModelBankIDs			
	        A reference where modelbank IDs are stored.

	@return An error code indicating if the function call was successful. KErrNone on success, otherwise
	        another of the system-wide error codes.

	@since  8.0
	*/
		IMPORT_C TInt GetAllClientModelBankIDs(
							RArray<TModelBankID>& aModelBankIDs );
	/**
	Returns all grammar IDs.

	@param  aGrammarIDs			
	        A reference where rule IDs are stored.

	@return An error code indicating if the function call was successful. KErrNone on success, otherwise
	        another of the system-wide error codes.

	@since  8.0
	*/
	IMPORT_C TInt GetAllGrammarIDs(RArray <TGrammarID>& aGrammarIDs );
	
	/**
	Returns all lexicons IDs.

	@param  aLexiconIDs	
	        A reference where lexicon IDs are stored.

	@return An error code indicating if the function call was successful. KErrNone on success, otherwise
	        another of the system-wide error codes.

	@since  8.0
	*/
	IMPORT_C TInt GetAllLexiconIDs(RArray <TLexiconID>& aLexiconIDs );

	/**
	Returns all modelbank IDs.

	@param  aModelBankIDs			
	        A reference where modelbank IDs are stored.

	@return An error code indicating if the function call was successful. KErrNone on success, otherwise
	        another of the system-wide error codes.

	@since  8.0
	*/
	IMPORT_C TInt GetAllModelBankIDs(
		RArray<TModelBankID>& aModelBankIDs );

	/**
	Returns all model IDs that exist in the specified model bank.

	@param  aModelBankID		
	        The model bank ID.
	@param  aModelIDs			
	        A reference where model IDs are stored.

	@return An error code indicating if the function call was successful. KErrNone on success, otherwise
	        another of the system-wide error codes.

	@since  8.0
	*/
	IMPORT_C TInt GetAllModelIDs( TModelBankID aModelBankID,
		RArray <TModelID>& aModelIDs );

	/**
	Checks if the rule is valid or not.

	@param  aGrammarID
	        The grammar ID.
	@param	aRuleID
			The rule ID.
	@param  aValid
	        A reference where the validity of the rule is set.

	@return An error code indicating if the function call was successful. KErrNone on success, otherwise
	        another of the system-wide error codes.

	@since  8.0
	*/
	IMPORT_C TInt GetRuleValidity( TGrammarID aGrammarID, TRuleID aRuleID,
		TBool& aValid );

	/**
	Returns all rule IDs that exist in the specified grammar.

	@param  aGrammarID			
	        The grammar ID.
	@param  aRuleIDs			
	        A reference where rule IDs are stored.

	@return An error code indicating if the function call was successful. KErrNone on success, otherwise
	        another of the system-wide error codes.

	@since  8.0
	*/
	IMPORT_C TInt GetAllRuleIDs( TGrammarID aGrammarID,
		RArray <TRuleID>& aRuleIDs );

	/**
	Creates a new model bank.

	@param  aModelBankID		
	        A reference where a new model bank IF is assigned to.

	@return An error code indicating if the function call was successful. KErrNone on success, otherwise
	        another of the system-wide error codes.

	@since  8.0
	*/
	IMPORT_C TInt CreateModelBank( TModelBankID& aModelBankID );

	/**
	Removes the specified model bank from the permanent storage.

	Removing a model bank will remove all models within the model bank.

	@param  aModelBankID		
	        The model bank ID.

	@return An error code indicating if the function call was successful. KErrNone on success, otherwise
	        another of the system-wide error codes.

	@since	8.0
	*/
	IMPORT_C TInt RemoveModelBank( TModelBankID aModelBankID );

	/**
	Returns the number of models available for training system model storage, based on available 
	disk space.

	@param  aAvailableStorage	
	        The number of models that can be contained in available storage.

	@return An error code indicating if the function call was successful. KErrNone on success, otherwise
	        another of the system-wide error codes.

	@since  8.0
	*/
	IMPORT_C TInt GetAvailableStorage( TInt& aAvailableStorage );

	/**
	Loads the specified parameters into the recognition engine.

	@param  aParameterId		
	        The array of parameter IDs.
	@param  aParameterValue		
	        The array of parameter values.

	@return An error code indicating if the function call was successful. KErrNone on success, otherwise
	        another of the system-wide error codes.

	@since  8.0
	*/
	IMPORT_C TInt LoadEngineParameters( const RArray<TInt>& aParameterId,
					const RArray<TInt>& aParameterValue );

	/**
	Sets the audio priority and preference for train, playback and recognition.

	@param  aPriority				
	        The priority for voice recognition.
	@param  aTrainPreference		
	        The preference for training.
	@param  aPlaybackPreference		
	        The preference for playback.
	@param  aRecognitionPreference	
	        The preference for recognition.

	@return An error code indicating if the function call was successful. KErrNone on success, otherwise
	        another of the system-wide error codes.

	@since  8.0

	@capability MultimediaDD
	            A process requesting or using this method that has MultimediaDD capability will
				always have precedence over a process that does not have MultimediaDD.
	*/
	IMPORT_C TInt SetAudioPriority( TInt aPriority, TInt aTrainPreference,
		TInt aPlaybackPreference, TInt aRecognitionPreference );

private:
	/**
	Private C++ constructor for this class.

	@since  8.0
	*/
	CSpeechRecognitionUtility();

	/**
	Second phase constructor for this class.

	@param  aSpeechRecognitionUtilityObserver		
	        A reference to the event observer class.

	@since  8.0
	*/
	void ConstructL(MSpeechRecognitionUtilityObserver& aSpeechRecognitionUtilityObserver);

private:
	CBody* iBody;
	friend class CBody;
};

#endif	// of __SPEECHRECOGNITIONUTILITY_H__

	// End of File